launchdarkly-server-sdk 8.19.0 → 8.20.0

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,87 @@
1
+ # frozen_string_literal: true
2
+
3
+ require "ldclient-rb/impl/repeating_task"
4
+
5
+ module LaunchDarkly
6
+ module Impl
7
+ module FileData
8
+ #
9
+ # Detects changes to a set of files by examining them on a fixed interval. Use it where file
10
+ # system change notifications are not available or not reliable. A change to the
11
+ # modification time or the size of any file invokes the callback. A file that appears or
12
+ # disappears is also a change. A file that cannot be examined counts as absent.
13
+ #
14
+ # The poller samples the files once per interval and compares only modification time and
15
+ # size. A rewrite that keeps both values is not detected.
16
+ #
17
+ # Detection is generous. The callback can run for a change that does not alter the
18
+ # effective data. Feed it into a {Reloader}, whose debouncing and skip-unchanged handling
19
+ # absorb the excess.
20
+ #
21
+ # @private
22
+ #
23
+ class Poller
24
+ # The observed state of one file, or its absence.
25
+ FileState = Struct.new(:exists, :mtime, :size)
26
+
27
+ ABSENT = FileState.new(false, nil, nil).freeze
28
+ private_constant :ABSENT
29
+
30
+ #
31
+ # Creates and starts a poller. It examines the files once before it returns, so only later
32
+ # changes invoke the callback. Call {#stop} to stop it.
33
+ #
34
+ # @param paths [Array<String>] absolute paths of the files to examine
35
+ # @param interval [Numeric] seconds between examinations
36
+ # @param on_change [#call] invoked with no arguments when a change is detected
37
+ # @param logger [Logger]
38
+ #
39
+ def initialize(paths, interval, on_change, logger)
40
+ @paths = paths
41
+ @on_change = on_change
42
+ @last = Poller.observe_all(paths)
43
+ @task = RepeatingTask.new(interval, interval, method(:examine), logger, "LD/FileDataPoller")
44
+ @task.start
45
+ end
46
+
47
+ #
48
+ # Stops the poller and waits for the worker thread to finish. A callback that is already
49
+ # running completes first.
50
+ #
51
+ def stop
52
+ @task.stop
53
+ end
54
+
55
+ #
56
+ # Examines every file and returns the observed states, in path order.
57
+ #
58
+ # @param paths [Array<String>]
59
+ # @return [Array<FileState>]
60
+ #
61
+ def self.observe_all(paths)
62
+ paths.map { |path| observe(path) }
63
+ end
64
+
65
+ #
66
+ # Examines one file. The state is that of the file a symbolic link leads to.
67
+ #
68
+ # @param path [String]
69
+ # @return [FileState]
70
+ #
71
+ def self.observe(path)
72
+ stat = File.stat(path)
73
+ FileState.new(true, stat.mtime, stat.size)
74
+ rescue SystemCallError
75
+ ABSENT
76
+ end
77
+
78
+ private def examine
79
+ current = Poller.observe_all(@paths)
80
+ changed = current != @last
81
+ @last = current
82
+ @on_change.call if changed
83
+ end
84
+ end
85
+ end
86
+ end
87
+ end
@@ -0,0 +1,578 @@
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
+
7
+ require "digest"
8
+
9
+ module LaunchDarkly
10
+ module Impl
11
+ module FileData
12
+ #
13
+ # Owns the reload cycle for a set of data files. It serializes reloads, debounces change
14
+ # signals, retains the last good result on failure (by not calling `apply`), retries after
15
+ # failures, holds back a file that was emptied before applying it, and skips no-op
16
+ # applications.
17
+ #
18
+ # Applications and editors rewrite files in place: they truncate the file, then write the new
19
+ # content. A load in between finds the file empty, or, for YAML, can find only a comment or
20
+ # "---", which the YAML parser reads as nothing. Whether a file with no entries is valid
21
+ # depends on its format (see {Document.parse}), so a parser cannot tell an emptied file from
22
+ # one in the middle of a rewrite. So a load that finds a file with no content (empty, white
23
+ # space, or YAML that is only a null), while the data currently applied has content from that
24
+ # file, holds the file back: it reads the other files, so that files emptied together are
25
+ # held back together, then keeps the current data and arms the retry, without reporting a
26
+ # failure. A file that cannot be read or parsed still fails the load. A YAML document such as
27
+ # `{}` is content, and is applied at once.
28
+ #
29
+ # A file is held back until it has stayed so, without being written, for the retry delay,
30
+ # counted from the load that read it. A change of its state (its modification time and size,
31
+ # read through any symbolic link) means it was written since a load last found it so, for
32
+ # example rewritten and truncated again between two loads, so the delay starts over. Each file
33
+ # is held back for at most five retry delays from the first load that held it back. The bound
34
+ # goes on across reads that find the file with content, and starts over only at a load that
35
+ # holds nothing back, whether that load applies, is skipped as unchanged, or fails, for each
36
+ # file it read. A load reads every file, even after one fails to read or parse, and fails with
37
+ # the first failure after them. So a file that keeps being rewritten, or files rewritten in
38
+ # turn, cannot hold the data back without end. A read that finds a file with content, even
39
+ # content that fails to parse, or finds it missing, ends its empty state, so its next emptying
40
+ # starts a new delay. The retry that a hold arms comes when the first held file's delay or
41
+ # bound is over, plus a tenth of the retry delay. A file that contributed no content to the
42
+ # data currently applied, such as a placeholder that has been empty from the start, a file
43
+ # that was missing, or a file whose emptying has been applied, is parsed at once. So is every
44
+ # file when there are no automatic retries, because nothing would read it again. After the
45
+ # delay, an empty JSON file fails to parse and the data stays; an empty YAML file is a
46
+ # document with no entries.
47
+ #
48
+ # The worker thread starts on the first {#reload_now} or {#trigger} call rather than in the
49
+ # constructor. A reloader can be constructed by a component whose lifecycle never uses it,
50
+ # and construction alone must not leak a thread.
51
+ #
52
+ # @private
53
+ #
54
+ class Reloader
55
+ # A settle window long enough to coalesce the burst of change notifications produced by a
56
+ # single file edit, and short enough to stay responsive. In seconds.
57
+ DEFAULT_DEBOUNCE_DELAY = 0.1
58
+
59
+ # Bounds how long a failed reload can go uncorrected when no further change notification
60
+ # arrives, for example when the failure came from reading a file mid-write. Reading a local
61
+ # file is cheap, so this can be short. In seconds.
62
+ DEFAULT_RETRY_DELAY = 1.0
63
+
64
+ # A file is held back for at most this many retry delays from the first load that held it
65
+ # back. The bound starts over at a load that holds nothing back.
66
+ MAX_HOLD_RETRY_DELAYS = 5
67
+
68
+ # A file whose content is in effect and that loads have found with no content: since when it
69
+ # has been so without being written, or nil once a load read it with content or found it
70
+ # missing; its {Poller::FileState} then; and when a load first held it back, or nil.
71
+ EmptyFile = Struct.new(:since, :state, :first_held)
72
+ private_constant :EmptyFile
73
+
74
+ #
75
+ # @param paths [Array<String>] the files to load, already resolved to absolute paths. The
76
+ # order is significant: it determines which file wins under the duplicate keys handling.
77
+ # @param logger [Logger]
78
+ # @param apply [#call] invoked with each successfully merged {MergeResult}. Calls are
79
+ # serialized, so implementations do not need their own synchronization against other
80
+ # reloads. An exception from `apply` is a failed reload: it is reported through
81
+ # `on_error`, the result is not remembered as applied, and the reload is retried.
82
+ # `apply` and `on_error` must not call back into {#stop}.
83
+ # @param on_error [#call, nil] invoked with the error when a reload fails, once per distinct
84
+ # failure. With automatic retries, repeats of an identical failure do not re-invoke it. A
85
+ # success re-arms it. The error is a {ReadError} when a file could not be read or parsed,
86
+ # a {MergeError} when the documents could not be combined or `check_document` rejected
87
+ # one, or the exception that `apply` raised. The reloader logs failures itself.
88
+ # @param duplicate_keys_handling [Symbol] one of the {DuplicateKeysHandling} values
89
+ # @param skip_missing_paths [Boolean] when true, a configured file that does not exist
90
+ # contributes no data, and the reload succeeds with the data of the files that exist.
91
+ # When false, a missing file fails the reload like any other read error.
92
+ # @param debounce_delay [Numeric] seconds to wait after a {#trigger} call for further calls
93
+ # to settle before reloading. If zero or negative, each trigger reloads at once.
94
+ # @param retry_delay [Numeric] seconds to wait after a failed reload before retrying
95
+ # automatically. A file whose content is in effect and that is found empty is held back
96
+ # for the same delay. If zero or negative, there is no automatic retry, and an empty file
97
+ # is parsed as it is.
98
+ # @param skip_unchanged [Boolean] if true, `apply` is not invoked when the files' raw
99
+ # contents are byte-identical to the last successfully applied contents.
100
+ # @param log_prefix [String] the prefix of every log line this reloader writes
101
+ # @param check_document [#call, nil] invoked with the path and the {Document} of each file
102
+ # that a load parsed, before the documents are combined. A {MergeError} that it raises
103
+ # fails the load in the same way as a file that cannot be parsed. When nil, every document
104
+ # is combined.
105
+ # @param clock [#call, nil] returns the seconds of a monotonic clock, for the time a file has
106
+ # been held back; nil for the system's. Scheduling always uses the system's clock.
107
+ #
108
+ def initialize(paths:, logger:, apply:, on_error: nil,
109
+ duplicate_keys_handling: DuplicateKeysHandling::FAIL,
110
+ skip_missing_paths: false,
111
+ debounce_delay: DEFAULT_DEBOUNCE_DELAY,
112
+ retry_delay: DEFAULT_RETRY_DELAY,
113
+ skip_unchanged: false,
114
+ log_prefix: "[LDClient]",
115
+ check_document: nil,
116
+ clock: nil)
117
+ @paths = paths
118
+ @logger = logger
119
+ @log_prefix = log_prefix
120
+ @apply = apply
121
+ @on_error = on_error
122
+ @check_document = check_document
123
+ @duplicate_keys_handling = duplicate_keys_handling
124
+ @skip_missing_paths = skip_missing_paths
125
+ @debounce_delay = debounce_delay
126
+ @retry_delay = retry_delay
127
+ @skip_unchanged = skip_unchanged
128
+ @clock = clock || method(:monotonic_now)
129
+
130
+ # Guards the scheduling state below and wakes the worker.
131
+ @mutex = Mutex.new
132
+ @cond = ConditionVariable.new
133
+ @worker = nil
134
+ @stopped = false
135
+ @trigger_pending = false
136
+ @requested_retry_delay = nil
137
+ @debounce_deadline = nil
138
+ @retry_deadline = nil
139
+
140
+ # Serializes the actual load work between reload_now and the worker.
141
+ @reload_mutex = Mutex.new
142
+ @last_good_digest = nil
143
+ @last_error_message = nil
144
+ # Whether each configured path contributed content to the data currently applied; the
145
+ # EmptyFile of each path whose content is in effect and that loads have found with no
146
+ # content since; whether the last load held a file back; and whether the load in progress
147
+ # holds one back. Only touched while holding @reload_mutex.
148
+ @applied_had_content = {}
149
+ @empty_files = {}
150
+ @read_again_pending = false
151
+ @holding_this_load = false
152
+ # The delay of the last retry that was armed. Only tests read it. Guarded by @mutex.
153
+ @last_armed_retry_delay = nil
154
+ end
155
+
156
+ #
157
+ # Synchronously loads the files and applies the result, or reports the failure. Use it for
158
+ # the initial load. A failure here schedules the same automatic retry as a failed
159
+ # triggered reload, and a load that holds back a file it finds empty arms the retry for when
160
+ # the file may be read as it is.
161
+ #
162
+ # @return [Boolean] true if the load succeeded, false if it failed or held back an empty file
163
+ #
164
+ def reload_now
165
+ ensure_started
166
+ retry_in = reload(retrying: false)
167
+ request_retry(retry_in) unless retry_in.nil?
168
+ retry_in.nil?
169
+ end
170
+
171
+ #
172
+ # The delay in seconds of the last retry that was armed, from the time it was armed. Only
173
+ # tests use it.
174
+ #
175
+ # @return [Numeric, nil]
176
+ #
177
+ def last_armed_retry_delay
178
+ @mutex.synchronize { @last_armed_retry_delay }
179
+ end
180
+
181
+ #
182
+ # Signals that the files may have changed and a reload should happen after the debounce
183
+ # delay. It never blocks. Signals that arrive while a reload is already pending are
184
+ # coalesced.
185
+ #
186
+ def trigger
187
+ ensure_started
188
+ @mutex.synchronize do
189
+ @trigger_pending = true
190
+ @cond.signal
191
+ end
192
+ end
193
+
194
+ #
195
+ # Stops the reloader. It does not wait for a reload that is already in progress. A reload
196
+ # wedged in a blocking file read must not be able to wedge shutdown. Such a reload can
197
+ # still deliver its result through `apply` or `on_error` shortly after this method
198
+ # returns, and consumers tolerate that. A reload that has not yet reached its callbacks
199
+ # when this method is called does not invoke them.
200
+ #
201
+ def stop
202
+ @mutex.synchronize do
203
+ @stopped = true
204
+ @cond.broadcast
205
+ end
206
+ end
207
+
208
+ private def ensure_started
209
+ @mutex.synchronize do
210
+ return if @stopped || !@worker.nil?
211
+
212
+ @worker = Thread.new { run }
213
+ @worker.name = "LD/FileDataReloader"
214
+ end
215
+ end
216
+
217
+ private def request_retry(delay)
218
+ return unless @retry_delay > 0
219
+
220
+ @mutex.synchronize do
221
+ @requested_retry_delay = [@requested_retry_delay, delay].compact.min
222
+ @cond.signal
223
+ end
224
+ end
225
+
226
+ private def run
227
+ loop do
228
+ action = next_action
229
+ break if action == :stop
230
+
231
+ # An unexpected error must not end the worker: no reload would happen after it.
232
+ begin
233
+ @logger.info { "#{@log_prefix} Reloading flag data after detecting a change" } if action == :reload
234
+ retry_in = reload(retrying: action == :retry)
235
+ @mutex.synchronize do
236
+ # A pending retry is superseded by this reload. The reload either succeeded, or it
237
+ # failed or held back a file and arms a fresh retry here.
238
+ if retry_in.nil? || @retry_delay <= 0
239
+ @retry_deadline = nil
240
+ else
241
+ @retry_deadline = monotonic_now + retry_in
242
+ @last_armed_retry_delay = retry_in
243
+ end
244
+ end
245
+ rescue => e
246
+ log_unexpected_error(e)
247
+ end
248
+ end
249
+ end
250
+
251
+ private def log_unexpected_error(error)
252
+ @logger.error { "#{@log_prefix} Unexpected error in file data reloader: #{error.inspect}" }
253
+ @logger.debug { "#{@log_prefix} Exception trace: #{error.backtrace}" }
254
+ end
255
+
256
+ #
257
+ # Waits until a reload is due. Returns :reload for a change-triggered reload, :retry for
258
+ # an automatic retry, or :stop.
259
+ #
260
+ private def next_action
261
+ @mutex.synchronize do
262
+ loop do
263
+ return :stop if @stopped
264
+
265
+ now = monotonic_now
266
+ if @trigger_pending
267
+ @trigger_pending = false
268
+ return :reload if @debounce_delay <= 0
269
+
270
+ @debounce_deadline = now + @debounce_delay
271
+ end
272
+ unless @requested_retry_delay.nil?
273
+ # A synchronous reload_now failed or held back a file. Arm the retry without
274
+ # reloading again at once. An already armed retry that comes sooner is kept.
275
+ deadline = now + @requested_retry_delay
276
+ @requested_retry_delay = nil
277
+ @retry_deadline = [@retry_deadline, deadline].compact.min
278
+ @last_armed_retry_delay = @retry_deadline - now
279
+ end
280
+ if !@debounce_deadline.nil? && now >= @debounce_deadline
281
+ @debounce_deadline = nil
282
+ return :reload
283
+ end
284
+ if !@retry_deadline.nil? && now >= @retry_deadline
285
+ @retry_deadline = nil
286
+ return :retry
287
+ end
288
+
289
+ deadlines = [@debounce_deadline, @retry_deadline].compact
290
+ timeout = deadlines.empty? ? nil : [deadlines.min - now, 0].max
291
+ @cond.wait(@mutex, timeout)
292
+ end
293
+ end
294
+ end
295
+
296
+ #
297
+ # Performs one full load of all configured files. Returns nil if it succeeded, or the
298
+ # seconds after which to retry if it failed or held back a file. A skipped no-op application
299
+ # counts as success. The whole set is re-read on every reload: entries are combined across
300
+ # files in order, so a change to one file can alter which file wins for a key.
301
+ #
302
+ private def reload(retrying: false)
303
+ @reload_mutex.synchronize do
304
+ # A trigger already queued when stop was called can still reach here.
305
+ return nil if stopped?
306
+
307
+ if retrying
308
+ if @read_again_pending
309
+ @logger.debug { "#{@log_prefix} Reading flag data again after a file was found empty" }
310
+ else
311
+ @logger.debug { "#{@log_prefix} Retrying flag data load after earlier failure" }
312
+ end
313
+ end
314
+ @read_again_pending = false
315
+ @holding_this_load = false
316
+ # The files that the load read and did not hold back, including those whose read or parse
317
+ # failed. A load reads every file unless an error it does not expect stops it.
318
+ reached = []
319
+ retry_in =
320
+ begin
321
+ load_files(reached)
322
+ rescue => e
323
+ # A failure that the load does not expect is retried like any other.
324
+ log_unexpected_error(e)
325
+ stopped? ? nil : @retry_delay
326
+ end
327
+ unless @holding_this_load
328
+ # A load that holds nothing back, whether it applies, is skipped or fails, starts the
329
+ # bound over for every file that it read: such a file is no longer held back, so its
330
+ # next rewrite is a new one.
331
+ reached.each do |path|
332
+ empty = @empty_files[path]
333
+ empty.first_held = nil unless empty.nil?
334
+ end
335
+ end
336
+ retry_in
337
+ end
338
+ end
339
+
340
+ # The body of {#reload}, while holding @reload_mutex.
341
+ private def load_files(reached)
342
+ documents = []
343
+ files = []
344
+ had_content = {}
345
+ held = []
346
+ # The first read or parse failure. The other files are still read, so that each of them is
347
+ # classified, and the load fails with it after them.
348
+ failure = nil
349
+ digest = Digest::SHA256.new
350
+ @paths.each do |path|
351
+ begin
352
+ # One read feeds both the digest and the parse, so the skip-unchanged digest can never
353
+ # disagree with the content that was applied.
354
+ content = FileData.read_file(path)
355
+ rescue ReadError => e
356
+ if e.missing
357
+ not_empty(path, reached)
358
+ else
359
+ reached << path
360
+ end
361
+ if e.missing && @skip_missing_paths
362
+ @logger.debug { "#{@log_prefix} File #{path} does not exist; it contributes no data" }
363
+ had_content[path] = false
364
+ append_to_digest(digest, path, nil)
365
+ files << FileSummary.new(path, false, 0, 0)
366
+ next
367
+ end
368
+ failure ||= e
369
+ next
370
+ end
371
+ # A file with no content, or YAML that the parser reads as nothing, such as only a
372
+ # comment, has no entries. A read can see that much of a file that is being written.
373
+ # Content with no JSON document is only parsed when the file is not held back, and then
374
+ # fails to parse.
375
+ document = nil
376
+ has_content = !FileData.blank?(content)
377
+ if has_content
378
+ begin
379
+ document = FileData.parse_file(path, content)
380
+ rescue ReadError => e
381
+ # Content that fails to parse is content: the file's empty state is over.
382
+ not_empty(path, reached)
383
+ failure ||= e
384
+ next
385
+ end
386
+ has_content = !document.equal?(Document::NONE)
387
+ end
388
+ if has_content
389
+ not_empty(path, reached)
390
+ elsif hold_back?(path, @clock.call)
391
+ # The clock is read after this file's own read, so a slow read of another file does
392
+ # not shorten its delay.
393
+ # The other files are still read, so that files emptied together start their delays
394
+ # in the same load.
395
+ @holding_this_load = true
396
+ held << path
397
+ next
398
+ else
399
+ reached << path
400
+ end
401
+ had_content[path] = has_content
402
+
403
+ append_to_digest(digest, path, content)
404
+ if document.nil?
405
+ begin
406
+ document = FileData.parse_file(path, content)
407
+ rescue ReadError => e
408
+ failure ||= e
409
+ next
410
+ end
411
+ end
412
+ begin
413
+ @check_document&.call(path, document)
414
+ rescue MergeError => e
415
+ failure ||= e
416
+ next
417
+ end
418
+ documents << document
419
+ files << FileSummary.new(path, true, 0, 0)
420
+ end
421
+ return record_failure(failure) unless failure.nil?
422
+ return hold_back(held, @clock.call) unless held.empty?
423
+
424
+ begin
425
+ merged = FileData.merge(documents,
426
+ duplicate_keys_handling: @duplicate_keys_handling,
427
+ logger: @logger)
428
+ rescue => e
429
+ return record_failure(e)
430
+ end
431
+
432
+ # Documents are the present files in order. Copy their counts onto the file summaries.
433
+ document_index = 0
434
+ files.each do |file|
435
+ next unless file.present
436
+
437
+ summary = merged.documents[document_index]
438
+ file.flags = summary.flags
439
+ file.segments = summary.segments
440
+ document_index += 1
441
+ end
442
+ merged.files = files
443
+
444
+ # stop may have been called while the files were being read. Deliver nothing then.
445
+ return nil if stopped?
446
+
447
+ # A success right after a failure must apply even when the content is unchanged since the
448
+ # last success. The consumer heard about the failure through on_error and may have moved
449
+ # to an interrupted state. Only apply tells it that things are good again.
450
+ recovering = !@last_error_message.nil?
451
+ hexdigest = digest.hexdigest
452
+ if @skip_unchanged && !recovering && hexdigest == @last_good_digest
453
+ remember_applied(had_content)
454
+ return nil
455
+ end
456
+
457
+ # Nothing is remembered until the consumer has accepted the result. A result that apply
458
+ # rejects must not become the baseline that skip-unchanged compares against, and must not
459
+ # count as a recovery.
460
+ begin
461
+ @apply.call(merged)
462
+ rescue => e
463
+ return record_failure(e)
464
+ end
465
+ @last_error_message = nil
466
+ @last_good_digest = hexdigest
467
+ remember_applied(had_content)
468
+ nil
469
+ end
470
+
471
+ # Adds a file to the skip-unchanged digest: its path, whether it is present, and its content.
472
+ # The same content in another file can parse differently, since the format comes from the
473
+ # name, and does not come from the same file.
474
+ private def append_to_digest(digest, path, content)
475
+ digest << path.b << "\0"
476
+ if content.nil?
477
+ digest << "-\0"
478
+ else
479
+ digest << "+" << content.bytesize.to_s << "\0" << content.b
480
+ end
481
+ end
482
+
483
+ # Records that a load found the file with content, even content that fails to parse, or
484
+ # missing: its empty state is over, so its next emptying starts a new delay even where a
485
+ # coarse modification time makes it look the same. Its bound goes on, so that files
486
+ # rewritten in turn stay bounded.
487
+ private def not_empty(path, reached)
488
+ reached << path
489
+ empty = @empty_files[path]
490
+ empty.since = nil unless empty.nil?
491
+ end
492
+
493
+ # Records what each file contributed to the data now in effect. The holds of the files start
494
+ # over.
495
+ private def remember_applied(had_content)
496
+ @applied_had_content = had_content
497
+ @empty_files.clear
498
+ end
499
+
500
+ #
501
+ # Decides whether a load that found a file with no content holds it back, because it may be
502
+ # in the middle of an in-place rewrite, and records since when it has been so. `now` is read
503
+ # after the file's own read.
504
+ #
505
+ private def hold_back?(path, now)
506
+ return false if @retry_delay <= 0 || !@applied_had_content[path]
507
+
508
+ state = Poller.observe(path)
509
+ empty = (@empty_files[path] ||= EmptyFile.new(nil, nil, nil))
510
+ if empty.since.nil? || empty.state != state
511
+ # Found empty for the first time since it had content, or written since a load last
512
+ # found it so: a new rewrite.
513
+ empty.since = now
514
+ empty.state = state
515
+ end
516
+ # After the delay the file is parsed. The entry stays, so later loads keep parsing it until
517
+ # it has content. Its bound starts over only at a load that holds nothing back.
518
+ return false if now - empty.since >= @retry_delay
519
+ return false if !empty.first_held.nil? && now - empty.first_held >= MAX_HOLD_RETRY_DELAYS * @retry_delay
520
+
521
+ empty.first_held ||= now
522
+ true
523
+ end
524
+
525
+ #
526
+ # Holds back a load that found files with no content. The current data stays and no failure
527
+ # is reported. Returns when to retry: when the delay or the bound of the first of the files
528
+ # is over, plus a tenth of the retry delay, so that a retry that comes a little early still
529
+ # finds it over.
530
+ #
531
+ private def hold_back(paths, now)
532
+ # stop may have been called while the files were being read. Arm no retry.
533
+ return nil if stopped?
534
+
535
+ @read_again_pending = true
536
+ retry_at = nil
537
+ paths.each do |path|
538
+ @logger.debug do
539
+ "#{@log_prefix} File #{path} is empty, possibly while it is being rewritten; reading it again before applying it"
540
+ end
541
+ empty = @empty_files[path]
542
+ over = [empty.since + @retry_delay, empty.first_held + MAX_HOLD_RETRY_DELAYS * @retry_delay].min
543
+ retry_at = over if retry_at.nil? || over < retry_at
544
+ end
545
+ [retry_at - now, 0].max + @retry_delay / 10.0
546
+ end
547
+
548
+ private def record_failure(error)
549
+ # stop may have been called while the files were being read. Deliver nothing then, and
550
+ # arm no retry.
551
+ return nil if stopped?
552
+
553
+ # With automatic retries, a persistent failure would repeat the same log entry and the
554
+ # same callback on every attempt. Repeats of an identical failure are logged at debug
555
+ # level and do not re-invoke on_error.
556
+ message = error.message
557
+ if message == @last_error_message
558
+ @logger.debug { "#{@log_prefix} Unable to load flags: #{message}" }
559
+ return @retry_delay
560
+ end
561
+
562
+ @last_error_message = message
563
+ @logger.error { "#{@log_prefix} Unable to load flags: #{message}" }
564
+ @on_error&.call(error)
565
+ @retry_delay
566
+ end
567
+
568
+ private def stopped?
569
+ @mutex.synchronize { @stopped }
570
+ end
571
+
572
+ private def monotonic_now
573
+ Process.clock_gettime(Process::CLOCK_MONOTONIC)
574
+ end
575
+ end
576
+ end
577
+ end
578
+ end