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
@@ -0,0 +1,519 @@
1
+ # frozen_string_literal: true
2
+
3
+ require "ldclient-rb/impl/repeating_task"
4
+ require "ldclient-rb/impl/util"
5
+
6
+ require "concurrent/atomics"
7
+ require "set"
8
+
9
+ module LaunchDarkly
10
+ module Impl
11
+ module FileData
12
+ #
13
+ # Detects changes to a set of files through file system change notifications. The
14
+ # notification mechanism comes from the optional `listen` gem, which the SDK does not depend
15
+ # on. Check {Watcher.available?} before constructing a watcher.
16
+ #
17
+ # On Linux the watcher uses `rb-inotify`, which `listen` depends on, to watch the directory of
18
+ # each file without descending into subdirectories. Elsewhere it uses `listen` itself, which
19
+ # scans the whole directory tree under each watched directory.
20
+ #
21
+ # The watcher observes the directory of each file, so a configured file that does not exist
22
+ # yet is picked up when it appears. Each directory is watched on its own: one that does not
23
+ # exist, or that is deleted while it is watched, is logged and retried once per second until
24
+ # it exists, while the other directories stay watched. When a retry sets up a watch, the
25
+ # callback runs once, so that a change made while there was no watch is not missed.
26
+ #
27
+ # A configured file can be a symbolic link to a file in another directory. The watcher also
28
+ # watches the directory of the link's target for the target's name, so that an edit to the
29
+ # target is reported. The links are resolved again after every reported change, after a retry
30
+ # sets up watches, and when a directory that holds a target is deleted, as happens when a
31
+ # Kubernetes ConfigMap volume is updated. A link that cannot be resolved, for example because
32
+ # its target's directory does not exist yet or was deleted, is resolved again once per second
33
+ # until its target is watched, and the callback then runs once.
34
+ #
35
+ # A change that none of those events reports is not followed: a link further along the chain
36
+ # that is pointed elsewhere while its old target stays, a configured directory that is itself
37
+ # a link and is pointed elsewhere, or a configured directory that is renamed and replaced.
38
+ # Deployments that switch files that way, such as a `current` link to a release directory,
39
+ # should use polling, which reads every configured path on each interval.
40
+ #
41
+ # @private
42
+ #
43
+ class Watcher
44
+ # Seconds between attempts to set up the watches after a failure.
45
+ RETRY_INTERVAL = 1.0
46
+
47
+ INOTIFY_EVENTS = [:create, :modify, :close_write, :attrib, :delete, :moved_to, :moved_from,
48
+ :delete_self, :move_self].freeze
49
+ private_constant :INOTIFY_EVENTS
50
+
51
+ # The inotify event flags that mean the watched directory itself is gone.
52
+ INOTIFY_DIRECTORY_LOST = [:delete_self, :move_self].freeze
53
+ private_constant :INOTIFY_DIRECTORY_LOST
54
+
55
+ # The watch on one real directory: the configured directories that resolve to it, the
56
+ # names of the configured files in it, the names of the files in it that configured
57
+ # symbolic links point to, and a callable that removes the watch. A directory is watched
58
+ # once, whatever the reasons, because a second watch on it would replace the first one's
59
+ # callback.
60
+ WatchedDirectory = Struct.new(:directories, :names, :targets, :close)
61
+ private_constant :WatchedDirectory
62
+
63
+ # The most symbolic links followed from one configured file, as in the operating system's
64
+ # own limit, so that a loop of links ends.
65
+ MAX_LINKS = 40
66
+ private_constant :MAX_LINKS
67
+
68
+ #
69
+ # Returns true if a change notification mechanism can be loaded.
70
+ #
71
+ # @return [Boolean]
72
+ #
73
+ def self.available?
74
+ inotify_available? || listen_available?
75
+ end
76
+
77
+ #
78
+ # Returns true if `rb-inotify` can be loaded. It is a dependency of `listen` on Linux and
79
+ # does not load on other platforms.
80
+ #
81
+ # @return [Boolean]
82
+ #
83
+ def self.inotify_available?
84
+ @inotify_available = load_library("rb-inotify") if @inotify_available.nil?
85
+ @inotify_available
86
+ end
87
+
88
+ #
89
+ # Returns true if the `listen` gem can be loaded.
90
+ #
91
+ # @return [Boolean]
92
+ #
93
+ def self.listen_available?
94
+ @listen_available = load_library("listen") if @listen_available.nil?
95
+ @listen_available
96
+ end
97
+
98
+ private_class_method def self.load_library(name)
99
+ require name
100
+ true
101
+ rescue LoadError, StandardError
102
+ false
103
+ end
104
+
105
+ #
106
+ # Creates and starts a watcher.
107
+ #
108
+ # @param paths [Array<String>] absolute paths of the files to watch
109
+ # @param on_change [#call] invoked with no arguments when one of the files changes
110
+ # @param logger [Logger]
111
+ #
112
+ def initialize(paths, on_change, logger)
113
+ @paths = paths
114
+ @on_change = on_change
115
+ @logger = logger
116
+ @stopped = Concurrent::AtomicBoolean.new(false)
117
+ @lock = Mutex.new
118
+ @retry_task = nil
119
+ @last_error_message = nil
120
+ # The directories of the configured paths, in configuration order. A directory is in
121
+ # @missing until it is watched, and then in @watched under its real path. The lock
122
+ # guards both, @retry_task, and @inotify.
123
+ @directories = paths.map { |p| File.dirname(p) }.uniq
124
+ @missing = Set.new(@directories)
125
+ @watched = {}
126
+ @inotify = nil
127
+ # True while a configured link's target is not watched, because the link cannot be
128
+ # resolved or its target's directory cannot be watched. The retry runs while it is true.
129
+ # The lock guards it.
130
+ @links_unresolved = false
131
+ @last_link_message = nil
132
+
133
+ try_start
134
+ refresh_links
135
+ schedule_retry unless @lock.synchronize { @missing.empty? }
136
+ end
137
+
138
+ #
139
+ # Stops the watcher. No callback runs after this method returns, apart from one that is
140
+ # already in progress.
141
+ #
142
+ def stop
143
+ return unless @stopped.make_true
144
+
145
+ closers, retry_task, inotify = @lock.synchronize do
146
+ state = [@watched.values.map(&:close), @retry_task, @inotify]
147
+ @watched.clear
148
+ @retry_task = nil
149
+ @inotify = nil
150
+ state
151
+ end
152
+ retry_task&.stop
153
+ closers.each(&:call)
154
+ inotify&.stop
155
+ end
156
+
157
+ #
158
+ # Starts the task that attempts to watch the missing directories once per second, unless
159
+ # it already runs or the watcher is stopped.
160
+ #
161
+ private def schedule_retry
162
+ @lock.synchronize do
163
+ return if @stopped.value || !@retry_task.nil?
164
+
165
+ @retry_task = RepeatingTask.new(RETRY_INTERVAL, RETRY_INTERVAL, method(:retry_start), @logger,
166
+ "LD/FileDataWatcherRetry")
167
+ @retry_task.start
168
+ end
169
+ end
170
+
171
+ private def retry_start
172
+ return if @stopped.value
173
+
174
+ added = try_start
175
+ linked = (added || @lock.synchronize { @links_unresolved }) ? refresh_links : false
176
+ # The task ends when nothing is missing and every link's target is watched. A directory
177
+ # lost meanwhile is back in @missing before its loss report calls schedule_retry, and a
178
+ # link that cannot be resolved sets @links_unresolved before refresh_links calls it, so
179
+ # either the task is kept here or that call starts a new one.
180
+ retry_task = @lock.synchronize do
181
+ next nil unless @missing.empty? && !@links_unresolved
182
+
183
+ task = @retry_task
184
+ @retry_task = nil
185
+ task
186
+ end
187
+ # This runs on the retry task's own thread, which RepeatingTask#stop allows.
188
+ retry_task&.stop
189
+ @on_change.call if (added || linked) && !@stopped.value
190
+ end
191
+
192
+ #
193
+ # Handles the loss of a watched directory. The notification mechanism reports it on its
194
+ # own thread. The watch ends with the directory, so it is removed, and a configured
195
+ # directory is set up again through the same retry as at start, once it exists. The other
196
+ # directories keep their watches. When the directory held the target of a configured link,
197
+ # the links are resolved again and the callback runs, since the file that the link names
198
+ # has changed.
199
+ #
200
+ private def directory_lost(real_directory)
201
+ entry = @lock.synchronize do
202
+ return if @stopped.value
203
+
204
+ e = @watched.delete(real_directory)
205
+ return if e.nil?
206
+
207
+ @missing.merge(e.directories)
208
+ e
209
+ end
210
+ if entry.directories.empty?
211
+ @logger.debug { "[LDClient] Directory #{real_directory} of a linked data file no longer exists; resolving the links again" }
212
+ else
213
+ @logger.warn { "[LDClient] Directory #{real_directory} no longer exists; its data files are watched again when it exists" }
214
+ end
215
+ entry.close.call
216
+ schedule_retry unless entry.directories.empty?
217
+ return if entry.targets.empty?
218
+
219
+ refresh_links
220
+ @on_change.call unless @stopped.value
221
+ end
222
+
223
+ #
224
+ # Watches each missing directory that exists now. Returns true if at least one watch was
225
+ # added. The directories that are still missing, and any watch that could not be set up,
226
+ # are logged together, so that an unchanged situation repeats at debug level.
227
+ #
228
+ private def try_start
229
+ added = false
230
+ missing = []
231
+ problems = []
232
+ @lock.synchronize { @directories.select { |d| @missing.include?(d) } }.each do |directory|
233
+ unless File.directory?(directory)
234
+ missing << directory
235
+ next
236
+ end
237
+ begin
238
+ added = true if watch_directory(directory)
239
+ rescue => e
240
+ problems << e.message
241
+ end
242
+ end
243
+ problems.unshift("directory does not exist: #{missing.join(', ')}") unless missing.empty?
244
+ if problems.empty?
245
+ @last_error_message = nil
246
+ else
247
+ log_setup_failure(problems.join("; "))
248
+ end
249
+ added
250
+ end
251
+
252
+ #
253
+ # Watches the real directory of a configured directory, and records the names of the
254
+ # configured files in it. Two configured directories can resolve to the same real
255
+ # directory, which then has one watch for the names in both. Returns false if the watcher
256
+ # is stopped.
257
+ #
258
+ private def watch_directory(directory)
259
+ real_directory = File.realpath(directory)
260
+ names = @paths.select { |p| File.dirname(p) == directory }.map { |p| File.basename(p) }
261
+ @lock.synchronize do
262
+ return false if @stopped.value
263
+
264
+ entry = @watched[real_directory]
265
+ if entry.nil?
266
+ entry = WatchedDirectory.new(Set.new, Set.new, Set.new, add_watch(real_directory))
267
+ @watched[real_directory] = entry
268
+ end
269
+ entry.directories << directory
270
+ entry.names.merge(names)
271
+ @missing.delete(directory)
272
+ end
273
+ true
274
+ end
275
+
276
+ #
277
+ # Resolves each configured file that is a symbolic link and records the target's name in
278
+ # the entry of the target's real directory, watching that directory if no entry has it yet.
279
+ # The targets of links that changed are dropped, and a watch that served only such targets
280
+ # is removed. A link that cannot be resolved, for example because its target's directory
281
+ # does not exist yet, or whose target's directory cannot be watched, keeps the retry
282
+ # running, which resolves the links again. Returns true if it added a watch or if a link
283
+ # now leads to a target it did not lead to before, which can be in a directory that is
284
+ # already watched.
285
+ #
286
+ private def refresh_links
287
+ desired = {}
288
+ problems = []
289
+ @paths.each do |p|
290
+ target = link_target(p)
291
+ if target
292
+ (desired[File.dirname(target)] ||= Set.new) << File.basename(target)
293
+ elsif File.symlink?(p)
294
+ problems << "cannot resolve the target of #{p}"
295
+ end
296
+ end
297
+ closers = []
298
+ added = false
299
+ @lock.synchronize do
300
+ return false if @stopped.value
301
+
302
+ # A new target in a directory that is already watched is a change. A directory that is
303
+ # not watched yet counts once its watch is added below, so a watch that keeps failing
304
+ # does not report a change on every retry.
305
+ desired.each do |real_directory, names|
306
+ entry = @watched[real_directory]
307
+ added = true if entry && !(names - entry.targets).empty?
308
+ end
309
+ @watched.each { |real_directory, entry| entry.targets = desired[real_directory] || Set.new }
310
+ @watched.delete_if do |_real_directory, entry|
311
+ next false unless entry.directories.empty? && entry.targets.empty?
312
+
313
+ closers << entry.close
314
+ true
315
+ end
316
+ desired.each do |real_directory, names|
317
+ next if @watched.key?(real_directory)
318
+
319
+ begin
320
+ @watched[real_directory] = WatchedDirectory.new(Set.new, Set.new, names, add_watch(real_directory))
321
+ added = true
322
+ rescue => e
323
+ problems << e.message
324
+ end
325
+ end
326
+ @links_unresolved = !problems.empty?
327
+ end
328
+ log_link_problems(problems)
329
+ close_later(closers) unless closers.empty?
330
+ schedule_retry unless problems.empty?
331
+ added
332
+ end
333
+
334
+ #
335
+ # Logs why a configured link's target is not watched. An unchanged situation repeats at
336
+ # debug level, apart from the setup failures that try_start logs.
337
+ #
338
+ private def log_link_problems(problems)
339
+ if problems.empty?
340
+ @last_link_message = nil
341
+ return
342
+ end
343
+ message = problems.join("; ")
344
+ if message == @last_link_message
345
+ @logger.debug { "[LDClient] Unable to watch the target of a linked data file: #{message}" }
346
+ else
347
+ @last_link_message = message
348
+ @logger.warn { "[LDClient] Unable to watch the target of a linked data file: #{message}" }
349
+ end
350
+ end
351
+
352
+ #
353
+ # Returns the path of the file that a configured symbolic link finally points to, with its
354
+ # directory resolved to a real path, or nil if the configured file is not a link, the
355
+ # target's directory does not exist, or the links loop. The target file itself need not
356
+ # exist, so that a link created ahead of its target is followed once the target appears.
357
+ #
358
+ # A relative link is relative to the real directory that holds it, so it is expanded
359
+ # against that directory's real path. Expanding it against the path as written would
360
+ # take a ".." to the wrong place when a directory in that path is itself a link.
361
+ #
362
+ private def link_target(path)
363
+ return nil unless File.symlink?(path)
364
+
365
+ target = path
366
+ MAX_LINKS.times do
367
+ real_directory = File.realpath(File.dirname(target))
368
+ return File.join(real_directory, File.basename(target)) unless File.symlink?(target)
369
+
370
+ target = File.expand_path(File.readlink(target), real_directory)
371
+ end
372
+ nil
373
+ rescue SystemCallError, NotImplementedError
374
+ nil
375
+ end
376
+
377
+ #
378
+ # Removes watches on a thread of its own. A watch can be removed from within one of its own
379
+ # callbacks, and stopping a `listen` listener waits for the thread that runs its callbacks.
380
+ #
381
+ private def close_later(closers)
382
+ thread = Thread.new do
383
+ closers.each do |close|
384
+ begin
385
+ close.call
386
+ rescue => e
387
+ Util.log_exception(@logger, "Unexpected error removing a file data watch", e)
388
+ end
389
+ end
390
+ end
391
+ thread.name = "LD/FileDataWatcherClose"
392
+ end
393
+
394
+ #
395
+ # Adds the notification mechanism's watch on a real directory and returns a callable that
396
+ # removes it. Called with the lock held, so that stop sees either no watch or a recorded
397
+ # one.
398
+ #
399
+ private def add_watch(real_directory)
400
+ Watcher.inotify_available? ? add_inotify_watch(real_directory) : start_listen(real_directory)
401
+ end
402
+
403
+ #
404
+ # Adds a watch on the directory itself, without descending into subdirectories, to the one
405
+ # inotify notifier, which is created with the first watch.
406
+ #
407
+ private def add_inotify_watch(real_directory)
408
+ @inotify ||= InotifyListener.new(INotify::Notifier.new, @logger)
409
+ watch = @inotify.watch(real_directory) { |event| inotify_event(real_directory, event) }
410
+ lambda do
411
+ begin
412
+ watch.close
413
+ rescue SystemCallError
414
+ # The kernel already removed the watch along with the directory.
415
+ end
416
+ end
417
+ end
418
+
419
+ private def inotify_event(real_directory, event)
420
+ return if @stopped.value
421
+
422
+ if (event.flags & INOTIFY_DIRECTORY_LOST).empty?
423
+ changed if watched_name?(real_directory, event.name)
424
+ else
425
+ directory_lost(real_directory)
426
+ end
427
+ end
428
+
429
+ #
430
+ # Watches a real directory with the `listen` gem, which reports paths under the real
431
+ # directory, so a reported path is matched by its directory and name.
432
+ #
433
+ private def start_listen(real_directory)
434
+ listener = Listen.to(real_directory) do |modified, added, removed|
435
+ next if @stopped.value
436
+
437
+ matched = (modified + added + removed).any? do |p|
438
+ File.dirname(p) == real_directory && watched_name?(real_directory, File.basename(p))
439
+ end
440
+ changed if matched
441
+ end
442
+ listener.start
443
+ -> { listener.stop }
444
+ end
445
+
446
+ #
447
+ # Reports a change to a watched file. The change can be to a configured link itself, so the
448
+ # links are resolved again first.
449
+ #
450
+ private def changed
451
+ return if @stopped.value
452
+
453
+ refresh_links
454
+ @on_change.call unless @stopped.value
455
+ end
456
+
457
+ #
458
+ # Returns true if the name is one of the configured files in the watched real directory, or
459
+ # the target of a configured link.
460
+ #
461
+ private def watched_name?(real_directory, name)
462
+ @lock.synchronize do
463
+ entry = @watched[real_directory]
464
+ !entry.nil? && (entry.names.include?(name) || entry.targets.include?(name))
465
+ end
466
+ end
467
+
468
+ private def log_setup_failure(message)
469
+ if message == @last_error_message
470
+ @logger.debug { "[LDClient] Unable to watch data files: #{message}" }
471
+ else
472
+ @last_error_message = message
473
+ @logger.error { "[LDClient] Unable to watch data files: #{message}" }
474
+ end
475
+ end
476
+
477
+ #
478
+ # Runs an inotify notifier on its own thread, takes watches for it over time, and stops it
479
+ # on request.
480
+ #
481
+ class InotifyListener
482
+ def initialize(notifier, logger)
483
+ @notifier = notifier
484
+ @thread = Thread.new do
485
+ begin
486
+ notifier.run
487
+ rescue IOError, SystemCallError
488
+ # The notifier was closed by stop.
489
+ rescue => e
490
+ Util.log_exception(logger, "Unexpected error in file data watcher", e)
491
+ end
492
+ end
493
+ @thread.name = "LD/FileDataWatcher"
494
+ end
495
+
496
+ #
497
+ # Adds a watch on a directory and returns the notifier's watch object, whose `close`
498
+ # removes the watch again.
499
+ #
500
+ def watch(directory, &callback)
501
+ @notifier.watch(directory, *INOTIFY_EVENTS, &callback)
502
+ end
503
+
504
+ #
505
+ # Stops the notifier and waits briefly for its thread. Closing the notifier ends the
506
+ # blocking read that the thread is in. A callback can call this on the notifier's own
507
+ # thread, which then ends when the callback returns.
508
+ #
509
+ def stop
510
+ @notifier.stop
511
+ @notifier.close
512
+ @thread.join(2) unless Thread.current == @thread
513
+ end
514
+ end
515
+ private_constant :InotifyListener
516
+ end
517
+ end
518
+ end
519
+ end
@@ -0,0 +1,7 @@
1
+ # frozen_string_literal: true
2
+
3
+ require "ldclient-rb/impl/file_data/document"
4
+ require "ldclient-rb/impl/file_data/merge"
5
+ require "ldclient-rb/impl/file_data/poller"
6
+ require "ldclient-rb/impl/file_data/reloader"
7
+ require "ldclient-rb/impl/file_data/watcher"
@@ -0,0 +1,174 @@
1
+ # frozen_string_literal: true
2
+
3
+ require "ldclient-rb/impl/file_data"
4
+ require "ldclient-rb/interfaces/overrides"
5
+
6
+ module LaunchDarkly
7
+ module Impl
8
+ module Integrations
9
+ #
10
+ # The file-based override source. It reads flag and segment overrides from one or more local
11
+ # files and reloads them as the files change. See
12
+ # {LaunchDarkly::Integrations::FileData.override_source} for the public API and its options.
13
+ #
14
+ # Flag overrides are currently experimental and subject to change.
15
+ #
16
+ # @private
17
+ #
18
+ class FileOverrideSource
19
+ include LaunchDarkly::Interfaces::Overrides::OverrideSource
20
+
21
+ LOG_PREFIX = "[LDClient] FileOverrideSource:"
22
+
23
+ #
24
+ # @param paths [Array<String>] absolute file paths, in precedence order
25
+ # @param duplicate_keys_handling [Symbol] `:fail` or `:ignore`
26
+ # @param change_detection [Symbol] `:polling` or `:watching`
27
+ # @param poll_interval [Numeric] seconds between examinations in polling mode
28
+ # @param logger [Logger]
29
+ #
30
+ def initialize(paths:, duplicate_keys_handling:, change_detection:, poll_interval:, logger:)
31
+ @paths = paths
32
+ @duplicate_keys_handling = duplicate_keys_handling
33
+ @change_detection = change_detection
34
+ @poll_interval = poll_interval
35
+ @logger = logger
36
+ @lock = Mutex.new
37
+ @reloader = nil
38
+ @change_detector = nil
39
+ @stopped = false
40
+ end
41
+
42
+ # @return [Array<String>]
43
+ attr_reader :paths
44
+
45
+ # @return [Symbol]
46
+ attr_reader :duplicate_keys_handling
47
+
48
+ # @return [Symbol]
49
+ attr_reader :change_detection
50
+
51
+ # @return [Numeric]
52
+ attr_reader :poll_interval
53
+
54
+ #
55
+ # Performs the initial load synchronously, so overrides present in the files are in effect
56
+ # when this method returns, then starts change detection. A file that does not exist yet
57
+ # contributes no overrides. A file that cannot be read or parsed is not fatal: the client
58
+ # runs with the last good overrides, the failure is logged, and the retry plus the change
59
+ # signal recover once the file is readable.
60
+ #
61
+ # (see LaunchDarkly::Interfaces::Overrides::OverrideSource#start)
62
+ #
63
+ def start(sink)
64
+ @lock.synchronize do
65
+ return if @stopped
66
+
67
+ @reloader = FileData::Reloader.new(
68
+ paths: @paths,
69
+ logger: @logger,
70
+ log_prefix: LOG_PREFIX,
71
+ duplicate_keys_handling: @duplicate_keys_handling,
72
+ skip_missing_paths: true,
73
+ skip_unchanged: true,
74
+ check_document: method(:reject_deleted_entries),
75
+ apply: lambda do |merged|
76
+ sink.set_overrides(merged.flags.values, merged.segments.values)
77
+ log_overrides_in_effect(merged)
78
+ end
79
+ )
80
+ end
81
+
82
+ @reloader.reload_now
83
+
84
+ @lock.synchronize do
85
+ return if @stopped
86
+
87
+ trigger = @reloader.method(:trigger)
88
+ @change_detector =
89
+ if @change_detection == :watching
90
+ FileData::Watcher.new(@paths, trigger, @logger)
91
+ else
92
+ FileData::Poller.new(@paths, @poll_interval, trigger, @logger)
93
+ end
94
+ end
95
+ end
96
+
97
+ # (see LaunchDarkly::Interfaces::Overrides::OverrideSource#stop)
98
+ def stop
99
+ reloader = nil
100
+ change_detector = nil
101
+ @lock.synchronize do
102
+ @stopped = true
103
+ reloader = @reloader
104
+ change_detector = @change_detector
105
+ @reloader = nil
106
+ @change_detector = nil
107
+ end
108
+ change_detector&.stop
109
+ reloader&.stop
110
+ end
111
+
112
+ #
113
+ # Fails the load of a file that contains a flag or segment entry marked as deleted, in the
114
+ # same way as a file that cannot be parsed. An override is removed by removing its entry or
115
+ # deleting its file, so a deleted entry is a mistake in the file. The sink rejects such a
116
+ # snapshot too. Checking here lets the logged failure name the file and the key.
117
+ #
118
+ # @param path [String]
119
+ # @param document [LaunchDarkly::Impl::FileData::Document]
120
+ # @raise [LaunchDarkly::Impl::FileData::MergeError] if an entry is marked as deleted
121
+ #
122
+ private def reject_deleted_entries(path, document)
123
+ { "flag" => document.flags, "segment" => document.segments }.each do |name, entries|
124
+ entries.each do |key, data|
125
+ # The data model treats any value of "deleted" other than false or null as deleted.
126
+ next unless data.is_a?(Hash) && data[:deleted]
127
+
128
+ raise FileData::MergeError,
129
+ "#{name} \"#{key}\" in #{path} is marked as deleted; remove the entry to remove its override"
130
+ end
131
+ end
132
+ end
133
+
134
+ #
135
+ # Reports the overrides now in effect and the file each came from. The reloader applies a
136
+ # snapshot only when the content changed, so this logs each change once.
137
+ #
138
+ # @param merged [LaunchDarkly::Impl::FileData::MergeResult]
139
+ #
140
+ private def log_overrides_in_effect(merged)
141
+ details = merged.files.map do |file|
142
+ if !file.present
143
+ "#{file.path}: absent"
144
+ elsif file.flags.zero? && file.segments.zero?
145
+ "#{file.path}: no entries"
146
+ else
147
+ "#{file.path}: #{counts_text(file.flags, file.segments)}"
148
+ end
149
+ end.join("; ")
150
+
151
+ if merged.empty?
152
+ @logger.info { "#{LOG_PREFIX} Flag overrides: none in effect (#{details})" }
153
+ else
154
+ @logger.info do
155
+ "#{LOG_PREFIX} Flag overrides in effect: #{counts_text(merged.flags.length, merged.segments.length)} (#{details})"
156
+ end
157
+ end
158
+ end
159
+
160
+ # Formats flag and segment counts, for example "2 flags, 1 segment".
161
+ private def counts_text(flags, segments)
162
+ parts = []
163
+ parts << pluralize(flags, "flag") if flags > 0
164
+ parts << pluralize(segments, "segment") if segments > 0
165
+ parts.join(", ")
166
+ end
167
+
168
+ private def pluralize(count, noun)
169
+ count == 1 ? "1 #{noun}" : "#{count} #{noun}s"
170
+ end
171
+ end
172
+ end
173
+ end
174
+ end