launchdarkly-server-sdk 8.19.1-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 (36) hide show
  1. checksums.yaml +4 -4
  2. data/lib/ldclient-rb/config.rb +11 -1
  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 +80 -3
  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/evaluator.rb +62 -18
  15. data/lib/ldclient-rb/impl/event_summarizer.rb +13 -2
  16. data/lib/ldclient-rb/impl/event_types.rb +11 -1
  17. data/lib/ldclient-rb/impl/file_data/document.rb +267 -0
  18. data/lib/ldclient-rb/impl/file_data/merge.rb +160 -0
  19. data/lib/ldclient-rb/impl/file_data/poller.rb +87 -0
  20. data/lib/ldclient-rb/impl/file_data/reloader.rb +578 -0
  21. data/lib/ldclient-rb/impl/file_data/watcher.rb +519 -0
  22. data/lib/ldclient-rb/impl/file_data.rb +7 -0
  23. data/lib/ldclient-rb/impl/integrations/file_override_source.rb +174 -0
  24. data/lib/ldclient-rb/impl/model/feature_flag.rb +34 -0
  25. data/lib/ldclient-rb/impl/model/segment.rb +34 -0
  26. data/lib/ldclient-rb/impl/overrides/layer.rb +133 -0
  27. data/lib/ldclient-rb/impl/overrides/overlay.rb +71 -0
  28. data/lib/ldclient-rb/impl/overrides/sink.rb +240 -0
  29. data/lib/ldclient-rb/impl/overrides.rb +5 -0
  30. data/lib/ldclient-rb/integrations/file_data.rb +181 -3
  31. data/lib/ldclient-rb/integrations/test_data/flag_builder.rb +1 -1
  32. data/lib/ldclient-rb/interfaces/overrides.rb +90 -0
  33. data/lib/ldclient-rb/interfaces.rb +1 -0
  34. data/lib/ldclient-rb/ldclient.rb +109 -28
  35. data/lib/ldclient-rb/version.rb +1 -1
  36. metadata +14 -2
@@ -1,5 +1,7 @@
1
+ require 'ldclient-rb/impl/file_data'
1
2
  require 'ldclient-rb/impl/integrations/file_data_source'
2
3
  require 'ldclient-rb/impl/integrations/file_data_source_v2'
4
+ require 'ldclient-rb/impl/integrations/file_override_source'
3
5
 
4
6
  module LaunchDarkly
5
7
  module Integrations
@@ -81,6 +83,11 @@ module LaunchDarkly
81
83
  # If the data source encounters any error in any file-- malformed content, a missing file, or a
82
84
  # duplicate key-- it will not load flags from any of the files.
83
85
  #
86
+ # The same file format serves the file-based override source, {FileData.override_source}, which
87
+ # supplies flag and segment overrides that take precedence over LaunchDarkly data instead of
88
+ # replacing the connection to LaunchDarkly. Flag overrides are currently experimental and subject
89
+ # to change.
90
+ #
84
91
  module FileData
85
92
  #
86
93
  # Returns a factory for the file data source component.
@@ -126,14 +133,14 @@ module LaunchDarkly
126
133
  # data_system_config = LaunchDarkly::DataSystemConfig.new(
127
134
  # initializers: [file_source]
128
135
  # )
129
- # config = LaunchDarkly::Config.new(data_system: data_system_config)
136
+ # config = LaunchDarkly::Config.new(data_system_config: data_system_config)
130
137
  #
131
138
  # @example Using as a synchronizer
132
139
  # file_source = LaunchDarkly::Integrations::FileData.data_source_v2(paths: ['flags.json'])
133
140
  # data_system_config = LaunchDarkly::DataSystemConfig.new(
134
141
  # synchronizers: [file_source]
135
142
  # )
136
- # config = LaunchDarkly::Config.new(data_system: data_system_config)
143
+ # config = LaunchDarkly::Config.new(data_system_config: data_system_config)
137
144
  #
138
145
  # @example Using as both initializer and synchronizer
139
146
  # file_source = LaunchDarkly::Integrations::FileData.data_source_v2(paths: ['flags.json'])
@@ -141,7 +148,7 @@ module LaunchDarkly
141
148
  # initializers: [file_source],
142
149
  # synchronizers: [file_source]
143
150
  # )
144
- # config = LaunchDarkly::Config.new(data_system: data_system_config)
151
+ # config = LaunchDarkly::Config.new(data_system_config: data_system_config)
145
152
  #
146
153
  def self.data_source_v2(options = {})
147
154
  paths = options[:paths] || []
@@ -149,6 +156,177 @@ module LaunchDarkly
149
156
 
150
157
  FileDataSourceV2Builder.new(paths, poll_interval)
151
158
  end
159
+
160
+ #
161
+ # Returns a builder for a file-based override source. Flag overrides are currently experimental
162
+ # and subject to change.
163
+ #
164
+ # Overrides are flag and segment definitions that take precedence over data received from
165
+ # LaunchDarkly at evaluation time, on a per-key basis. They exist for resilience during an
166
+ # incident. An operator can force one or more flags to a known state on a running application,
167
+ # whether or not the application can reach LaunchDarkly, by writing them to a file. The override
168
+ # stays in effect until it is removed from the file. Flags not present in the files are
169
+ # completely unaffected.
170
+ #
171
+ # The files use the same document format as the file data source: a JSON or YAML document with
172
+ # optional `flags`, `flagValues`, and `segments` members. A `flagValues` entry expands into a
173
+ # flag that is on and serves the given value as its fallthrough for every context. Such a flag is
174
+ # not available to client-side SDKs, so `all_flags_state` with `client_side_only: true` leaves it
175
+ # out, even when the flag it overrides is available to them. To override such a flag, define it
176
+ # in `flags` with `"clientSide": true`. When several files are configured, their
177
+ # entries are combined in the configured order, and the duplicate keys handling decides what
178
+ # happens when the same key appears in more than one file.
179
+ #
180
+ # A file whose name ends in `.yaml` or `.yml`, in any case, is read as YAML, and any other file is
181
+ # read as JSON. Files must be UTF-8. Whether a JSON file may contain comments or repeated keys
182
+ # depends on the application's version of the `json` gem.
183
+ #
184
+ # A reload replaces the entire set of overrides, so removing an entry from a file removes the
185
+ # override. A configured file that does not exist contributes no overrides. It can be created
186
+ # later, and deleting a file removes its overrides. A file that exists but cannot be read or
187
+ # parsed fails that whole reload. The previously loaded overrides stay in effect, the failure is
188
+ # logged, and the source retries after a short delay and recovers on its own once the file is
189
+ # readable. A file that contains an entry marked as deleted fails to load, and the overrides in
190
+ # effect stay; to remove an override, remove its entry or delete the file. Whenever the set of
191
+ # overrides in effect changes, including at startup, the source logs the overrides in effect
192
+ # and what each file supplied, at Info level.
193
+ #
194
+ # Files can be rewritten in place: if the source finds a file empty while it is being rewritten,
195
+ # it keeps the overrides in effect until the new content is written. To remove a file's
196
+ # overrides, delete the file or write a document with no entries, such as `{}`. An empty JSON
197
+ # file is not a valid document. For a YAML file, replacing its contents in one operation, such
198
+ # as by renaming a fully written temporary file over it, avoids briefly applying a partly
199
+ # written file.
200
+ #
201
+ # An evaluation that an override affects, directly or through a prerequisite or segment, is
202
+ # marked: its reason reports {EvaluationReason#override_affected}, it produces no individual
203
+ # analytics event, and it is counted under a separate summary counter.
204
+ #
205
+ # Pass the returned builder to {LaunchDarkly::DataSystem::ConfigBuilder#overrides}. The
206
+ # configuration is validated when the client is created, and an invalid configuration raises
207
+ # `ArgumentError` from `LDClient.new`.
208
+ #
209
+ # @example
210
+ # overrides = LaunchDarkly::Integrations::FileData.override_source(paths: ["/etc/launchdarkly/overrides.json"])
211
+ # config = LaunchDarkly::Config.new(data_system_config: LaunchDarkly::DataSystem.default.overrides(overrides).build)
212
+ # client = LaunchDarkly::LDClient.new(sdk_key, config)
213
+ #
214
+ # @param options [Hash] the configuration options
215
+ # @option options [Array<String>, String] :paths One or more files, in precedence order. Required.
216
+ # Each path must be a non-empty String, absolute or relative to the current working directory.
217
+ # @option options [Symbol] :duplicate_keys_handling What to do when the same key appears in more
218
+ # than one file. `:fail` (the default) treats the reload as failed and keeps the previous
219
+ # overrides. `:ignore` keeps the entry from the first configured file that defines the key.
220
+ # @option options [Symbol] :change_detection How the source detects file changes. `:polling` (the
221
+ # default) examines the files on an interval and works on every file system, including network
222
+ # mounts and directories whose contents are swapped through symbolic links. `:watching` uses file
223
+ # system change notifications through the `listen` gem, which the host application must provide.
224
+ # Watching follows edits to the configured files and to the targets of configured symbolic links,
225
+ # including the update of a mounted Kubernetes ConfigMap. It does not follow a deployment that
226
+ # points a link further along the path, or a configured directory, at another location, such as a
227
+ # `current` link to a release directory, or that replaces a configured directory. Use polling for
228
+ # such deployments.
229
+ # @option options [Numeric] :poll_interval Seconds between examinations of the files in polling
230
+ # mode. The default is 1. An interval below 1 is raised to 1 with a warning.
231
+ # @return [FileOverrideSourceBuilder] a builder for {LaunchDarkly::DataSystem::ConfigBuilder#overrides}
232
+ #
233
+ def self.override_source(options = {})
234
+ FileOverrideSourceBuilder.new(options)
235
+ end
236
+ end
237
+
238
+ #
239
+ # Builder for the file-based override source. Create it with {FileData.override_source}.
240
+ #
241
+ # Flag overrides are currently experimental and subject to change.
242
+ #
243
+ class FileOverrideSourceBuilder
244
+ # The default interval, in seconds, between examinations of the files in polling mode.
245
+ DEFAULT_POLL_INTERVAL = 1
246
+
247
+ # The shortest allowed polling interval, in seconds. A configured interval below this is raised
248
+ # to it. The minimum exists only to prevent a tight loop over the file system.
249
+ MINIMUM_POLL_INTERVAL = 1
250
+
251
+ DUPLICATE_KEYS_HANDLING_VALUES = [:fail, :ignore].freeze
252
+ CHANGE_DETECTION_VALUES = [:polling, :watching].freeze
253
+ OPTION_KEYS = [:paths, :duplicate_keys_handling, :change_detection, :poll_interval].freeze
254
+ private_constant :DUPLICATE_KEYS_HANDLING_VALUES, :CHANGE_DETECTION_VALUES, :OPTION_KEYS
255
+
256
+ #
257
+ # @param options [Hash] see {FileData.override_source}
258
+ #
259
+ def initialize(options)
260
+ raise ArgumentError, "options for the file-based override source must be a Hash" unless options.is_a?(Hash)
261
+
262
+ @options = options
263
+ end
264
+
265
+ #
266
+ # Builds the override source. Called by the SDK when the client is created.
267
+ #
268
+ # @param sdk_key [String] unused
269
+ # @param config [LaunchDarkly::Config] the client configuration, for its logger
270
+ # @return [LaunchDarkly::Interfaces::Overrides::OverrideSource]
271
+ # @raise [ArgumentError] if the options are invalid
272
+ #
273
+ def build(sdk_key, config)
274
+ unknown = @options.keys - OPTION_KEYS
275
+ raise ArgumentError, "unknown options for the file-based override source: #{unknown.join(', ')}" unless unknown.empty?
276
+
277
+ paths = Array(@options[:paths])
278
+ raise ArgumentError, "no file paths were specified for the file-based override source" if paths.empty?
279
+
280
+ invalid = paths.reject { |path| path.is_a?(String) && !path.empty? }
281
+ unless invalid.empty?
282
+ raise ArgumentError,
283
+ "file paths for the file-based override source must be non-empty strings; got #{invalid.map(&:inspect).join(', ')}"
284
+ end
285
+ paths = Impl::FileData.absolute_paths(paths)
286
+ # A path listed more than once would make every entry of that file a duplicate of itself, so
287
+ # the repeats are dropped and the first occurrence keeps its place in the order. File names
288
+ # on Windows ignore case, so there paths that differ only in case name the same file.
289
+ unique_paths = Gem.win_platform? ? paths.uniq(&:downcase) : paths.uniq
290
+ if unique_paths.size != paths.size
291
+ config.logger.warn do
292
+ "#{Impl::Integrations::FileOverrideSource::LOG_PREFIX} File paths list the same file more than once; the repeats are ignored"
293
+ end
294
+ paths = unique_paths
295
+ end
296
+
297
+ duplicate_keys_handling = @options.fetch(:duplicate_keys_handling, :fail)
298
+ unless DUPLICATE_KEYS_HANDLING_VALUES.include?(duplicate_keys_handling)
299
+ raise ArgumentError,
300
+ "unrecognized duplicate keys handling #{duplicate_keys_handling.inspect} for the file-based override source"
301
+ end
302
+
303
+ change_detection = @options.fetch(:change_detection, :polling)
304
+ unless CHANGE_DETECTION_VALUES.include?(change_detection)
305
+ raise ArgumentError, "unrecognized change detection mode #{change_detection.inspect} for the file-based override source"
306
+ end
307
+ if change_detection == :watching && !Impl::FileData::Watcher.available?
308
+ raise ArgumentError, "change detection mode :watching for the file-based override source requires the listen gem"
309
+ end
310
+
311
+ poll_interval = @options.fetch(:poll_interval, DEFAULT_POLL_INTERVAL)
312
+ unless poll_interval.is_a?(Numeric)
313
+ raise ArgumentError, "poll interval #{poll_interval.inspect} for the file-based override source must be a number"
314
+ end
315
+ if change_detection == :polling && poll_interval < MINIMUM_POLL_INTERVAL
316
+ config.logger.warn do
317
+ "#{Impl::Integrations::FileOverrideSource::LOG_PREFIX} Poll interval #{poll_interval}s is below the minimum; using #{MINIMUM_POLL_INTERVAL}s"
318
+ end
319
+ poll_interval = MINIMUM_POLL_INTERVAL
320
+ end
321
+
322
+ Impl::Integrations::FileOverrideSource.new(
323
+ paths: paths,
324
+ duplicate_keys_handling: duplicate_keys_handling,
325
+ change_detection: change_detection,
326
+ poll_interval: poll_interval,
327
+ logger: config.logger
328
+ )
329
+ end
152
330
  end
153
331
 
154
332
  #
@@ -181,7 +181,7 @@ module LaunchDarkly
181
181
  # @return [FlagBuilder] the builder
182
182
  #
183
183
  def value_for_all(value)
184
- variations(value).variation_for_all(0)
184
+ variations(value).variation_for_all(0).off_variation(0)
185
185
  end
186
186
 
187
187
  #
@@ -0,0 +1,90 @@
1
+ # frozen_string_literal: true
2
+
3
+ module LaunchDarkly
4
+ module Interfaces
5
+ #
6
+ # Interfaces for flag overrides. Overrides are flag and segment definitions that take
7
+ # precedence over data received from LaunchDarkly at evaluation time, on a per-key basis.
8
+ # They exist for resilience during an incident. An operator can force one or more flags to
9
+ # a known state on a running client, whether or not the client can reach LaunchDarkly.
10
+ #
11
+ # Flag overrides are currently experimental and subject to change.
12
+ #
13
+ module Overrides
14
+ #
15
+ # Receives the contents of the SDK's override store. The SDK implements it and passes it
16
+ # to an {OverrideSource}'s `start` method. Override sources call it. They do not implement it.
17
+ #
18
+ # Flag overrides are currently experimental and subject to change.
19
+ #
20
+ module OverrideSink
21
+ #
22
+ # Replaces the entire override store with the given flag and segment definitions. Each
23
+ # call is a full snapshot. Entries absent from the call are removed. Empty collections
24
+ # clear the store.
25
+ #
26
+ # Each definition is either a data model object, as produced by
27
+ # `LaunchDarkly::Impl::Model.deserialize`, or a hash in the flag or segment data model.
28
+ # The SDK itself marks the entries as overrides. A snapshot that contains a flag or segment
29
+ # marked as deleted is rejected with `ArgumentError`, and the store keeps its contents.
30
+ #
31
+ # This method is safe to call from any thread. Calls are serialized by the SDK, and the
32
+ # new contents are visible to evaluations when the call returns.
33
+ #
34
+ # @param flags [Enumerable<LaunchDarkly::Impl::Model::FeatureFlag, Hash>] full flag definitions
35
+ # @param segments [Enumerable<LaunchDarkly::Impl::Model::Segment, Hash>] full segment definitions
36
+ # @return [void]
37
+ #
38
+ def set_overrides(flags, segments)
39
+ raise NotImplementedError, "#{self.class} must implement #set_overrides"
40
+ end
41
+ end
42
+
43
+ #
44
+ # Supplies flag and segment overrides that take precedence over LaunchDarkly data at
45
+ # evaluation time, on a per-key basis.
46
+ #
47
+ # An override source is not a data source. It does not take part in the data system's
48
+ # initializer and synchronizer pipeline. The override store it populates has no effect on
49
+ # the client's initialization status, data availability, or data source status.
50
+ #
51
+ # To configure an override source, use {LaunchDarkly::DataSystem::ConfigBuilder#overrides}.
52
+ #
53
+ # Flag overrides are currently experimental and subject to change.
54
+ #
55
+ module OverrideSource
56
+ #
57
+ # Begins supplying overrides to the sink and returns without blocking on long-running
58
+ # work. An implementation performs an initial load synchronously, then pushes a full
59
+ # replacement snapshot to the sink whenever its backing data changes, until `stop` is
60
+ # called. A failed load leaves the previously supplied store untouched by not calling
61
+ # the sink.
62
+ #
63
+ # The SDK calls this method at most once, before any call to `stop`. This method is not
64
+ # intended to fail. A source that cannot load its data logs the failure and keeps retrying,
65
+ # as the SDK's file-based source does. A configuration error belongs in the builder's
66
+ # `build`, where it is raised when the client is created. If this method does raise, the
67
+ # client still starts: the SDK logs the exception, stops the source, removes any snapshot
68
+ # the source supplied, and the client runs without overrides.
69
+ #
70
+ # @param sink [OverrideSink]
71
+ # @return [void]
72
+ #
73
+ def start(sink)
74
+ raise NotImplementedError, "#{self.class} must implement #start"
75
+ end
76
+
77
+ #
78
+ # Stops the source and releases any resources it holds. An exception raised from it is
79
+ # logged and does not stop the client from shutting down. A snapshot that the source
80
+ # supplies after the SDK begins to stop it is ignored.
81
+ #
82
+ # @return [void]
83
+ #
84
+ def stop
85
+ raise NotImplementedError, "#{self.class} must implement #stop"
86
+ end
87
+ end
88
+ end
89
+ end
90
+ end
@@ -7,3 +7,4 @@ require "ldclient-rb/interfaces/big_segment_store"
7
7
  require "ldclient-rb/interfaces/migrations"
8
8
  require "ldclient-rb/interfaces/hooks"
9
9
  require "ldclient-rb/interfaces/plugins"
10
+ require "ldclient-rb/interfaces/overrides"
@@ -84,6 +84,8 @@ module LaunchDarkly
84
84
  # Each flag lets the matching cached-data warning log once per client.
85
85
  @cached_data_evaluation_warned = Concurrent::AtomicBoolean.new(false)
86
86
  @cached_data_all_flags_warned = Concurrent::AtomicBoolean.new(false)
87
+ # Set after the first warning that all_flags_state returned only override entries before initialization.
88
+ @all_flags_overrides_only_warned = Concurrent::AtomicBoolean.new(false)
87
89
 
88
90
  start_up(wait_for_sec)
89
91
  end
@@ -512,7 +514,11 @@ module LaunchDarkly
512
514
  next LaunchDarkly::Impl::EvaluationWithHookResult.new(detail, {stage: stage, tracker: tracker})
513
515
  end
514
516
 
515
- detail = LaunchDarkly::Impl::Evaluator.error_result(LaunchDarkly::EvaluationReason::ERROR_WRONG_TYPE, default_stage.to_s)
517
+ # The type mismatch replaces the reason. The evaluation read the same definitions, so the new
518
+ # reason keeps the override-affected marking.
519
+ reason = LaunchDarkly::EvaluationReason.error(LaunchDarkly::EvaluationReason::ERROR_WRONG_TYPE)
520
+ .with_override_affected(detail.reason.override_affected)
521
+ detail = EvaluationDetail.new(default_stage.to_s, nil, reason)
516
522
  tracker = Impl::Migrations::OpTracker.new(@config.logger, key, flag, context, detail, default_stage)
517
523
 
518
524
  LaunchDarkly::Impl::EvaluationWithHookResult.new(detail, {stage: default_stage, tracker: tracker})
@@ -632,14 +638,22 @@ module LaunchDarkly
632
638
 
633
639
  check_forked
634
640
 
641
+ override_features = nil
635
642
  unless initialized?
636
643
  if @data_system.store.initialized?
637
644
  if @cached_data_all_flags_warned.make_true
638
645
  @config.logger.warn { "Called all_flags_state before client initialization; using last known values from data store. This message is logged once." }
639
646
  end
640
647
  else
648
+ # No data from LaunchDarkly is available. When the override store holds flags, the state
649
+ # contains only those, read from the override store itself: a store that is not
650
+ # initialized can still hold LaunchDarkly data, which the state must not include.
651
+ # Without override flags the state is invalid, as it is without an override source.
652
+ override_features = @data_system.override_items(Impl::DataStore::FEATURES)
653
+ if override_features.empty?
641
654
  @config.logger.warn { "Called all_flags_state before client initialization. Data store not available; returning empty state" }
642
655
  return FeatureFlagsState.new(false)
656
+ end
643
657
  end
644
658
  end
645
659
 
@@ -649,14 +663,28 @@ module LaunchDarkly
649
663
  return FeatureFlagsState.new(false)
650
664
  end
651
665
 
652
- begin
653
- features = @data_system.store.all(Impl::DataStore::FEATURES)
654
- rescue => exn
655
- Impl::Util.log_exception(@config.logger, "Unable to read flags for all_flags_state", exn)
656
- return FeatureFlagsState.new(false)
666
+ valid = true
667
+ if override_features
668
+ if @all_flags_overrides_only_warned.make_true
669
+ @config.logger.warn { "Called all_flags_state before client initialization; returning only flags from the override store. This message is logged once." }
670
+ end
671
+ features = override_features
672
+ else
673
+ begin
674
+ features = @data_system.store.all(Impl::DataStore::FEATURES)
675
+ rescue => exn
676
+ Impl::Util.log_exception(@config.logger, "Unable to read flags for all_flags_state", exn)
677
+ # Overrides only add to the state. Without them the state is invalid and empty here, so
678
+ # with them it holds the override flags and stays invalid. A client-side SDK bootstrapped
679
+ # from the state uses its flags whatever $valid says (js-client-sdk 3.x and the 4.x browser
680
+ # SDK only log a warning), so the overridden values still reach it.
681
+ features = @data_system.override_items(Impl::DataStore::FEATURES)
682
+ return FeatureFlagsState.new(false) if features.empty?
683
+ valid = false
684
+ end
657
685
  end
658
686
 
659
- state = FeatureFlagsState.new(true)
687
+ state = FeatureFlagsState.new(valid)
660
688
  client_only = options[:client_side_only] || false
661
689
  with_reasons = options[:with_reasons] || false
662
690
  details_only_if_tracked = options[:details_only_for_tracked_flags] || false
@@ -668,21 +696,38 @@ module LaunchDarkly
668
696
  (eval_result, eval_state) = @evaluator.evaluate(f, context)
669
697
  detail = eval_result.detail
670
698
  rescue => exn
671
- detail = EvaluationDetail.new(nil, nil, EvaluationReason::error(EvaluationReason::ERROR_EXCEPTION))
699
+ # The flag definition was read before the failure, so its own marker decides the marking.
700
+ reason = EvaluationReason::error(EvaluationReason::ERROR_EXCEPTION).with_override_affected(override_item?(f))
701
+ detail = EvaluationDetail.new(nil, nil, reason)
672
702
  Impl::Util.log_exception(@config.logger, "Error evaluating flag \"#{k}\" in all_flags_state", exn)
673
703
  end
674
704
 
675
705
  requires_experiment_data = experiment?(f, detail.reason)
706
+ track_events = f[:trackEvents] || requires_experiment_data
707
+ track_reason = requires_experiment_data
708
+ debug_events_until_date = f[:debugEventsUntilDate]
709
+ # A failed evaluation has no result, so the flag's own marker decides, as it does for the
710
+ # reason.
711
+ override_affected = eval_result.nil? ? override_item?(f) : eval_result.override_affected
712
+ if override_affected
713
+ # A consumer of this state sends individual events according to these fields. An
714
+ # override-affected evaluation produces no individual events, so the state turns them off
715
+ # for this flag. The flag, its value, and its reason stay.
716
+ track_events = false
717
+ track_reason = false
718
+ debug_events_until_date = nil
719
+ end
676
720
  flag_state = {
677
721
  key: f[:key],
678
722
  value: detail.value,
679
723
  variation: detail.variation_index,
680
724
  reason: detail.reason,
681
- prerequisites: eval_state.prerequisites,
725
+ # A failed evaluation has no evaluation state, so it reports no prerequisites.
726
+ prerequisites: eval_state&.prerequisites,
682
727
  version: f[:version],
683
- trackEvents: f[:trackEvents] || requires_experiment_data,
684
- trackReason: requires_experiment_data,
685
- debugEventsUntilDate: f[:debugEventsUntilDate],
728
+ trackEvents: track_events,
729
+ trackReason: track_reason,
730
+ debugEventsUntilDate: debug_events_until_date,
686
731
  }
687
732
 
688
733
  state.add_flag(flag_state, with_reasons, details_only_if_tracked)
@@ -770,21 +815,29 @@ module LaunchDarkly
770
815
  return detail, nil, context.error
771
816
  end
772
817
 
818
+ override_feature = nil
773
819
  if @data_system.data_availability != Impl::DataSystem::DataAvailability::REFRESHED
774
820
  if @data_system.data_availability == Impl::DataSystem::DataAvailability::CACHED
775
821
  if @cached_data_evaluation_warned.make_true
776
822
  @config.logger.warn { "[LDClient] Client has not finished initializing; using last known values from feature store. This message is logged once." }
777
823
  end
778
824
  else
779
- @config.logger.error { "[LDClient] Client has not finished initializing; feature store unavailable, returning default value" }
780
- detail = Evaluator.error_result(EvaluationReason::ERROR_CLIENT_NOT_READY, default)
781
- record_unknown_flag_eval(key, context, default, detail.reason, with_reasons)
782
- return detail, nil, "client not initialized"
825
+ # No data from LaunchDarkly is available. A flag that the override store holds is served,
826
+ # read from the override store itself. Every other flag takes the not-ready path, as
827
+ # without an override source: a store that is not initialized can still hold
828
+ # LaunchDarkly data, which the SDK must not serve.
829
+ override_feature = override_flag(key)
830
+ if override_feature.nil?
831
+ @config.logger.error { "[LDClient] Client has not finished initializing; feature store unavailable, returning default value" }
832
+ detail = Evaluator.error_result(EvaluationReason::ERROR_CLIENT_NOT_READY, default)
833
+ record_unknown_flag_eval(key, context, default, detail.reason, with_reasons)
834
+ return detail, nil, "client not initialized"
835
+ end
783
836
  end
784
837
  end
785
838
 
786
839
  begin
787
- feature = @data_system.store.get(Impl::DataStore::FEATURES, key)
840
+ feature = override_feature || @data_system.store.get(Impl::DataStore::FEATURES, key)
788
841
  rescue
789
842
  # Ignored
790
843
  end
@@ -799,25 +852,37 @@ module LaunchDarkly
799
852
  begin
800
853
  (res, _) = @evaluator.evaluate(feature, context)
801
854
  unless res.prereq_evals.nil?
855
+ # Each prerequisite record carries the marking of the prerequisite's own evaluation, not
856
+ # the marking of the evaluation that requested it.
802
857
  res.prereq_evals.each do |prereq_eval|
803
- record_prereq_flag_eval(prereq_eval.prereq_flag, prereq_eval.prereq_of_flag, context, prereq_eval.detail, with_reasons)
858
+ record_prereq_flag_eval(prereq_eval.prereq_flag, prereq_eval.prereq_of_flag, context, prereq_eval.detail,
859
+ with_reasons, prereq_eval.override_affected)
804
860
  end
805
861
  end
806
862
  detail = res.detail
807
863
  if detail.default_value?
808
864
  detail = EvaluationDetail.new(default, nil, detail.reason)
809
865
  end
810
- record_flag_eval(feature, context, detail, default, with_reasons)
866
+ record_flag_eval(feature, context, detail, default, with_reasons, res.override_affected)
811
867
  [detail, feature, nil]
812
868
  rescue => exn
813
869
  Impl::Util.log_exception(@config.logger, "Error evaluating feature flag \"#{key}\"", exn)
814
- detail = Evaluator.error_result(EvaluationReason::ERROR_EXCEPTION, default)
815
- record_flag_eval_error(feature, context, default, detail.reason, with_reasons)
870
+ # The flag definition was read before the failure, so its own marker decides the marking.
871
+ reason = EvaluationReason.error(EvaluationReason::ERROR_EXCEPTION).with_override_affected(override_item?(feature))
872
+ detail = EvaluationDetail.new(default, nil, reason)
873
+ record_flag_eval_error(feature, context, default, detail.reason, with_reasons, override_item?(feature))
816
874
  [detail, feature, exn.to_s]
817
875
  end
818
876
  end
819
877
 
820
- private def record_flag_eval(flag, context, detail, default, with_reasons)
878
+ # Returns the override store's entry for the flag key, or nil.
879
+ private def override_flag(key)
880
+ return nil unless key.respond_to?(:to_sym)
881
+
882
+ @data_system.override_items(Impl::DataStore::FEATURES)[key.to_sym]
883
+ end
884
+
885
+ private def record_flag_eval(flag, context, detail, default, with_reasons, override_affected)
821
886
  add_experiment_data = experiment?(flag, detail.reason)
822
887
  @event_processor.record_eval_event(
823
888
  context,
@@ -831,11 +896,12 @@ module LaunchDarkly
831
896
  flag[:debugEventsUntilDate],
832
897
  nil,
833
898
  flag[:samplingRatio],
834
- !!flag[:excludeFromSummaries]
899
+ !!flag[:excludeFromSummaries],
900
+ override_affected
835
901
  )
836
902
  end
837
903
 
838
- private def record_prereq_flag_eval(prereq_flag, prereq_of_flag, context, detail, with_reasons)
904
+ private def record_prereq_flag_eval(prereq_flag, prereq_of_flag, context, detail, with_reasons, override_affected)
839
905
  add_experiment_data = experiment?(prereq_flag, detail.reason)
840
906
  @event_processor.record_eval_event(
841
907
  context,
@@ -849,13 +915,15 @@ module LaunchDarkly
849
915
  prereq_flag[:debugEventsUntilDate],
850
916
  prereq_of_flag[:key],
851
917
  prereq_flag[:samplingRatio],
852
- !!prereq_flag[:excludeFromSummaries]
918
+ !!prereq_flag[:excludeFromSummaries],
919
+ override_affected
853
920
  )
854
921
  end
855
922
 
856
- private def record_flag_eval_error(flag, context, default, reason, with_reasons)
923
+ private def record_flag_eval_error(flag, context, default, reason, with_reasons, override_affected)
857
924
  @event_processor.record_eval_event(context, flag[:key], flag[:version], nil, default, with_reasons ? reason : nil, default,
858
- flag[:trackEvents], flag[:debugEventsUntilDate], nil, flag[:samplingRatio], !!flag[:excludeFromSummaries])
925
+ flag[:trackEvents], flag[:debugEventsUntilDate], nil, flag[:samplingRatio], !!flag[:excludeFromSummaries],
926
+ override_affected)
859
927
  end
860
928
 
861
929
  #
@@ -866,8 +934,21 @@ module LaunchDarkly
866
934
  # @param with_reasons [Boolean]
867
935
  #
868
936
  private def record_unknown_flag_eval(flag_key, context, default, reason, with_reasons)
937
+ # Nothing was read from the override store, so the evaluation is not marked.
869
938
  @event_processor.record_eval_event(context, flag_key, nil, nil, default, with_reasons ? reason : nil, default,
870
- false, nil, nil, 1, false)
939
+ false, nil, nil, 1, false, false)
940
+ end
941
+
942
+ #
943
+ # Whether a stored flag carries the override marker. The FeatureStore interface documents its
944
+ # entities as hashes, and a custom store can return one. Only the SDK's model objects carry the
945
+ # marker; a hash never came from the override store.
946
+ #
947
+ # @param item [Object] a flag as returned by the store
948
+ # @return [Boolean]
949
+ #
950
+ private def override_item?(item)
951
+ item.respond_to?(:override?) && item.override?
871
952
  end
872
953
 
873
954
  private def experiment?(flag, reason)
@@ -1,3 +1,3 @@
1
1
  module LaunchDarkly
2
- VERSION = "8.19.1" # x-release-please-version
2
+ VERSION = "8.20.0" # x-release-please-version
3
3
  end
metadata CHANGED
@@ -1,13 +1,13 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: launchdarkly-server-sdk
3
3
  version: !ruby/object:Gem::Version
4
- version: 8.19.1
4
+ version: 8.20.0
5
5
  platform: java
6
6
  authors:
7
7
  - LaunchDarkly
8
8
  bindir: bin
9
9
  cert_chain: []
10
- date: 2026-10-23 00:00:00.000000000 Z
10
+ date: 2026-11-12 00:00:00.000000000 Z
11
11
  dependencies:
12
12
  - !ruby/object:Gem::Dependency
13
13
  name: aws-sdk-dynamodb
@@ -404,11 +404,18 @@ files:
404
404
  - lib/ldclient-rb/impl/event_summarizer.rb
405
405
  - lib/ldclient-rb/impl/event_types.rb
406
406
  - lib/ldclient-rb/impl/expiring_cache.rb
407
+ - lib/ldclient-rb/impl/file_data.rb
408
+ - lib/ldclient-rb/impl/file_data/document.rb
409
+ - lib/ldclient-rb/impl/file_data/merge.rb
410
+ - lib/ldclient-rb/impl/file_data/poller.rb
411
+ - lib/ldclient-rb/impl/file_data/reloader.rb
412
+ - lib/ldclient-rb/impl/file_data/watcher.rb
407
413
  - lib/ldclient-rb/impl/flag_tracker.rb
408
414
  - lib/ldclient-rb/impl/integrations/consul_impl.rb
409
415
  - lib/ldclient-rb/impl/integrations/dynamodb_impl.rb
410
416
  - lib/ldclient-rb/impl/integrations/file_data_source.rb
411
417
  - lib/ldclient-rb/impl/integrations/file_data_source_v2.rb
418
+ - lib/ldclient-rb/impl/integrations/file_override_source.rb
412
419
  - lib/ldclient-rb/impl/integrations/redis_impl.rb
413
420
  - lib/ldclient-rb/impl/integrations/test_data/test_data_source.rb
414
421
  - lib/ldclient-rb/impl/integrations/test_data/test_data_source_v2.rb
@@ -421,6 +428,10 @@ files:
421
428
  - lib/ldclient-rb/impl/model/segment.rb
422
429
  - lib/ldclient-rb/impl/model/serialization.rb
423
430
  - lib/ldclient-rb/impl/non_blocking_thread_pool.rb
431
+ - lib/ldclient-rb/impl/overrides.rb
432
+ - lib/ldclient-rb/impl/overrides/layer.rb
433
+ - lib/ldclient-rb/impl/overrides/overlay.rb
434
+ - lib/ldclient-rb/impl/overrides/sink.rb
424
435
  - lib/ldclient-rb/impl/repeating_task.rb
425
436
  - lib/ldclient-rb/impl/retry_state.rb
426
437
  - lib/ldclient-rb/impl/sampler.rb
@@ -449,6 +460,7 @@ files:
449
460
  - lib/ldclient-rb/interfaces/flag_tracker.rb
450
461
  - lib/ldclient-rb/interfaces/hooks.rb
451
462
  - lib/ldclient-rb/interfaces/migrations.rb
463
+ - lib/ldclient-rb/interfaces/overrides.rb
452
464
  - lib/ldclient-rb/interfaces/plugins.rb
453
465
  - lib/ldclient-rb/ldclient.rb
454
466
  - lib/ldclient-rb/migrations.rb