fix: Keep overrides through an in-place rewrite of their files

contract-tests/Gemfile

@@ -8,6 +8,9 @@ gem "puma", "~> 8.0"
 gem "rackup", "~> 2.2"
 gem 'sinatra', '>= 4.1'
 
+# The file-based override source uses the listen gem for its watching change detection mode.
+gem 'listen', '~> 3.3'
+
 gem 'rubocop', '~> 1.37', group: 'development'
 gem 'rubocop-performance', '~> 1.15', group: 'development'
 

contract-tests/client_entity.rb

@@ -56,7 +56,12 @@ def initialize(log, config)
         opts[:payload_filter_key] = data_system_config[:payloadFilter]
       end
 
+      # Flag overrides are an option of the FDv2 data system configuration.
+      data_system.overrides(build_override_source(config[:overrides])) if config[:overrides]
+
       opts[:data_system_config] = data_system.build
+    elsif config[:overrides]
+      raise ArgumentError, "flag overrides require the data system to be configured"
     elsif config[:streaming]
       streaming = config[:streaming]
       opts[:stream_uri] = streaming[:baseUri] unless streaming[:baseUri].nil?
@@ -365,6 +370,23 @@ def close
     builder
   end
 
+  #
+  # Builds the file-based override source from the `overrides` block of the contract test
+  # configuration.
+  #
+  # @param overrides_config [Hash] the overrides configuration
+  # @return [Object] a builder for LaunchDarkly::DataSystem::ConfigBuilder#overrides
+  #
+  private def build_override_source(overrides_config)
+    options = { paths: overrides_config[:filePaths] }
+    if overrides_config[:duplicateKeysHandling]
+      options[:duplicate_keys_handling] = overrides_config[:duplicateKeysHandling].to_sym
+    end
+    options[:change_detection] = overrides_config[:changeDetection].to_sym if overrides_config[:changeDetection]
+    set_optional_time_prop(overrides_config, :pollIntervalMs, options, :poll_interval)
+    LaunchDarkly::Integrations::FileData.override_source(options)
+  end
+
   #
   # Builds a persistent data store from the contract test configuration.
   #

contract-tests/service.rb

@@ -17,7 +17,7 @@
 }
 
 set :bind, '0.0.0.0'
-set :port, 9000
+set :port, (ENV['PORT'] || 9000).to_i
 set :logging, false
 
 clients = {}
@@ -55,6 +55,7 @@
       'flag-change-listeners',
       'flag-value-change-listeners',
       'fdv1-fallback',
+      'flag-overrides',
     ],
   }.to_json
 end

lib/ldclient-rb/config.rb

@@ -736,14 +736,18 @@ class DataSystemConfig
     # @param data_store [LaunchDarkly::Interfaces::FeatureStore, nil] The (optional) data store
     # @param fdv1_fallback_synchronizer [#build(String, Config), nil]
     #   The (optional) builder for FDv1-compatible fallback synchronizer
+    # @param overrides [#build(String, Config), nil] The (optional) builder for an override source.
+    #   Flag overrides are currently experimental and subject to change.
     #
     def initialize(initializers: nil, synchronizers: nil,
-                   data_store_mode: LaunchDarkly::Interfaces::DataSystem::DataStoreMode::READ_ONLY, data_store: nil, fdv1_fallback_synchronizer: nil)
+                   data_store_mode: LaunchDarkly::Interfaces::DataSystem::DataStoreMode::READ_ONLY, data_store: nil, fdv1_fallback_synchronizer: nil,
+                   overrides: nil)
       @initializers = initializers
       @synchronizers = synchronizers
       @data_store_mode = data_store_mode
       @data_store = data_store
       @fdv1_fallback_synchronizer = fdv1_fallback_synchronizer
+      @overrides = overrides
     end
 
     # The initializer builders for the data system. Each builder responds to build(sdk_key, config) and returns an Initializer.
@@ -765,5 +769,11 @@ def initialize(initializers: nil, synchronizers: nil,
     # The FDv1-compatible fallback synchronizer builder. Responds to build(sdk_key, config) and returns a Synchronizer.
     # @return [#build(String, Config), nil]
     attr_reader :fdv1_fallback_synchronizer
+
+    # The override source builder. Responds to build(sdk_key, config) and returns an
+    # {LaunchDarkly::Interfaces::Overrides::OverrideSource}. Flag overrides are currently
+    # experimental and subject to change.
+    # @return [#build(String, Config), nil]
+    attr_reader :overrides
   end
 end

lib/ldclient-rb/data_system/config_builder.rb

@@ -23,6 +23,7 @@ def initialize
         @fdv1_fallback_synchronizer = nil
         @data_store_mode = LaunchDarkly::Interfaces::DataSystem::DataStoreMode::READ_ONLY
         @data_store = nil
+        @overrides = nil
       end
 
       #
@@ -85,6 +86,38 @@ def data_store(data_store, store_mode)
         self
       end
 
+      #
+      # Configures the SDK with an override source. Flag overrides are currently experimental and
+      # subject to change.
+      #
+      # Overrides are flag and segment definitions that take precedence over data received from
+      # LaunchDarkly at evaluation time, on a per-key basis. They exist for resilience during an
+      # incident. Overrides let an operator force one or more flags to a known state on a running
+      # client, whether or not the client can reach LaunchDarkly. Flags not present in the override
+      # data are completely unaffected.
+      #
+      # The override source is not a data source. It has no effect on the client's initialization
+      # status, data availability, or data source status. Without a configured source, or while
+      # the source supplies no overrides, the SDK behaves as it would without this feature.
+      #
+      # At most one override source can be configured. A later call replaces an earlier one.
+      #
+      # When the client is offline, the source is not built or started: no overrides are served,
+      # and a configuration error in the source is not reported. The SDK logs a warning instead.
+      #
+      # @example
+      #   overrides = LaunchDarkly::Integrations::FileData.override_source(paths: ["/etc/launchdarkly/overrides.json"])
+      #   config = LaunchDarkly::Config.new(data_system: LaunchDarkly::DataSystem.default.overrides(overrides))
+      #
+      # @param source [#build(String, Config), nil] a builder that responds to build(sdk_key, config)
+      #   and returns a {LaunchDarkly::Interfaces::Overrides::OverrideSource}, or nil to remove one
+      # @return [ConfigBuilder] self for chaining
+      #
+      def overrides(source)
+        @overrides = source
+        self
+      end
+
       #
       # Builds the data system configuration.
       #
@@ -96,7 +129,8 @@ def build
           synchronizers: @synchronizers,
           data_store_mode: @data_store_mode,
           data_store: @data_store,
-          fdv1_fallback_synchronizer: @fdv1_fallback_synchronizer
+          fdv1_fallback_synchronizer: @fdv1_fallback_synchronizer,
+          overrides: @overrides
         )
       end
     end

lib/ldclient-rb/evaluation_detail.rb

@@ -150,6 +150,15 @@ class EvaluationReason
     # @return [Symbol]
     attr_reader :big_segments_status
 
+    # True if an override affected this evaluation, directly or transitively. It is true when the
+    # evaluated flag came from the SDK's override store. It is also true when a prerequisite flag at
+    # any depth, or a segment read during the evaluation, came from the override store. In the JSON
+    # representation, the `overrideAffected` property appears only when this is true.
+    #
+    # Flag overrides are currently experimental and subject to change.
+    # @return [Boolean]
+    attr_reader :override_affected
+
     # Returns an instance whose {#kind} is {#OFF}.
     # @return [EvaluationReason]
     def self.off
@@ -216,12 +225,14 @@ def ==(other)
       if other.is_a? EvaluationReason
         @kind == other.kind && @rule_index == other.rule_index && @rule_id == other.rule_id &&
           @prerequisite_key == other.prerequisite_key && @error_kind == other.error_kind &&
-          @big_segments_status == other.big_segments_status
+          @big_segments_status == other.big_segments_status &&
+          @override_affected == other.override_affected
       elsif other.is_a? Hash
         @kind.to_s == other[:kind] && @rule_index == other[:ruleIndex] && @rule_id == other[:ruleId] &&
           @prerequisite_key == other[:prerequisiteKey] &&
           (other[:errorKind] == @error_kind.nil? ? nil : @error_kind.to_s) &&
-          (other[:bigSegmentsStatus] == @big_segments_status.nil? ? nil : @big_segments_status.to_s)
+          (other[:bigSegmentsStatus] == @big_segments_status.nil? ? nil : @big_segments_status.to_s) &&
+          !!other[:overrideAffected] == @override_affected
       end
     end
 
@@ -286,6 +297,8 @@ def as_json(*) # parameter is unused, but may be passed if we're using the json
       unless @big_segments_status.nil?
         ret[:bigSegmentsStatus] = @big_segments_status
       end
+      # The property is written only when true, so the wire format of an ordinary evaluation is unchanged.
+      ret[:overrideAffected] = true if @override_affected
       ret
     end
 
@@ -312,22 +325,41 @@ def [](key)
         @error_kind.nil? ? nil : @error_kind.to_s
       when :bigSegmentsStatus
         @big_segments_status.nil? ? nil : @big_segments_status.to_s
+      when :overrideAffected
+        @override_affected
       else
         nil
       end
     end
 
     def with_big_segments_status(big_segments_status)
       return self if @big_segments_status == big_segments_status
-      EvaluationReason.new(@kind, @rule_index, @rule_id, @prerequisite_key, @error_kind, @in_experiment, big_segments_status)
+      EvaluationReason.new(@kind, @rule_index, @rule_id, @prerequisite_key, @error_kind, @in_experiment,
+        big_segments_status, @override_affected)
+    end
+
+    #
+    # Returns a reason that is the same as this one apart from the {#override_affected} indicator.
+    # Returns this instance when the indicator already has the given value.
+    #
+    # Flag overrides are currently experimental and subject to change.
+    #
+    # @param override_affected [Boolean]
+    # @return [EvaluationReason]
+    #
+    def with_override_affected(override_affected)
+      override_affected = !!override_affected
+      return self if @override_affected == override_affected
+      EvaluationReason.new(@kind, @rule_index, @rule_id, @prerequisite_key, @error_kind, @in_experiment,
+        @big_segments_status, override_affected)
     end
 
     #
     # Constructor that sets all properties. Applications should not normally use this constructor,
     # but should use class methods like {#off} to avoid creating unnecessary instances.
     #
     def initialize(kind, rule_index, rule_id, prerequisite_key, error_kind, in_experiment=nil,
-        big_segments_status = nil)
+        big_segments_status = nil, override_affected = false)
       @kind = kind.to_sym
       @rule_index = rule_index
       @rule_id = rule_id
@@ -337,6 +369,7 @@ def initialize(kind, rule_index, rule_id, prerequisite_key, error_kind, in_exper
       @error_kind = error_kind
       @in_experiment = in_experiment
       @big_segments_status = big_segments_status
+      @override_affected = !!override_affected
     end
 
     private_class_method def self.make_error(error_kind)

lib/ldclient-rb/events.rb

@@ -44,7 +44,8 @@ def record_eval_event(
       debug_until = nil,
       prereq_of = nil,
       sampling_ratio = nil,
-      exclude_from_summaries = false
+      exclude_from_summaries = false,
+      override_affected = false
     )
     end
 
@@ -176,10 +177,11 @@ def record_eval_event(
       debug_until = nil,
       prereq_of = nil,
       sampling_ratio = nil,
-      exclude_from_summaries = false
+      exclude_from_summaries = false,
+      override_affected = false
     )
       post_to_inbox(LaunchDarkly::Impl::EvalEvent.new(timestamp, context, key, version, variation, value, reason,
-        default, track_events, debug_until, prereq_of, sampling_ratio, exclude_from_summaries))
+        default, track_events, debug_until, prereq_of, sampling_ratio, exclude_from_summaries, override_affected))
     end
 
     def record_identify_event(context)
@@ -328,8 +330,10 @@ def dispatch_event(event, outbox)
       will_add_full_event = false
       debug_event = nil
       if event.is_a?(LaunchDarkly::Impl::EvalEvent)
-        will_add_full_event = event.track_events
-        if should_debug_event(event)
+        # An override-affected evaluation appears only in the summary counters. It produces no
+        # individual feature event and no debug event, whatever the flag's configuration requests.
+        will_add_full_event = event.track_events && !event.override_affected
+        if !event.override_affected && should_debug_event(event)
           debug_event = LaunchDarkly::Impl::DebugEvent.new(event)
         end
       else
@@ -630,18 +634,22 @@ def make_output_events(events, summary)
       summary.counters.each do |flagKey, flagInfo|
         counters = []
         flagInfo.versions.each do |version, variations|
-          variations.each do |variation, counter|
-            c = {
-              value: counter.value,
-              count: counter.count,
-            }
-            c[:variation] = variation unless variation.nil?
-            if version.nil?
-              c[:unknown] = true
-            else
-              c[:version] = version
+          variations.each do |variation, counters_by_marker|
+            counters_by_marker.each do |override_affected, counter|
+              c = {
+                value: counter.value,
+                count: counter.count,
+              }
+              c[:variation] = variation unless variation.nil?
+              if version.nil?
+                c[:unknown] = true
+              else
+                c[:version] = version
+              end
+              # The marker is present only for override-affected counters, like the unknown marker.
+              c[:overrideAffected] = true if override_affected
+              counters.push(c)
             end
-            counters.push(c)
           end
         end
         flags[flagKey] = { default: flagInfo.default, counters: counters, contextKinds: flagInfo.context_kinds.to_a }