fix: Honor x-ld-fd-fallback header in fdv2 initializer phase

Prior to this change, the Ruby SDK only inspected the x-ld-fd-fallback
response header on FDv2 synchronizer responses. If an initializer
received the header, the signal was silently dropped and the SDK would
continue attempting subsequent initializers and FDv2 synchronizers
rather than reverting to FDv1.

The Initializer fetch contract now returns a FetchResult that pairs the
existing Result<Basis> with a fallback_to_fdv1 boolean. The FDv2 data
system branches on the new flag, applying any accompanying Basis before
swapping the synchronizer list for the FDv1 fallback builder, so
evaluations can serve the server-provided payload while FDv1 spins up.
When no FDv1 fallback is configured, the data system logs and clears
the synchronizer list, mirroring the synchronizer-triggered path.

Update.revert_to_fdv1 is renamed to Update.fallback_to_fdv1 with an
alias retained for backwards compatibility while FDv2 is in early
access. A shared LaunchDarkly::Impl::DataSystem.fdv1_fallback_requested?
helper replaces the duplicated header-string checks across the polling
and streaming data sources.

Author: keelerm84

lib/ldclient-rb/impl/data_system.rb

@@ -247,8 +247,9 @@ class Update
         # @return [LaunchDarkly::Interfaces::DataSource::ErrorInfo, nil] Error information if applicable
         attr_reader :error
 
-        # @return [Boolean] Whether to revert to FDv1
-        attr_reader :revert_to_fdv1
+        # @return [Boolean] Whether the LaunchDarkly server has instructed the SDK to
+        #   fall back to the FDv1 protocol.
+        attr_reader :fallback_to_fdv1
 
         # @return [String, nil] The environment ID if available
         attr_reader :environment_id
@@ -257,16 +258,20 @@ class Update
         # @param state [Symbol] The state of the data source
         # @param change_set [ChangeSet, nil] The change set if available
         # @param error [LaunchDarkly::Interfaces::DataSource::ErrorInfo, nil] Error information if applicable
-        # @param revert_to_fdv1 [Boolean] Whether to revert to FDv1
+        # @param fallback_to_fdv1 [Boolean] Whether to fall back to FDv1
         # @param environment_id [String, nil] The environment ID if available
         #
-        def initialize(state:, change_set: nil, error: nil, revert_to_fdv1: false, environment_id: nil)
+        def initialize(state:, change_set: nil, error: nil, fallback_to_fdv1: false, environment_id: nil)
           @state = state
           @change_set = change_set
           @error = error
-          @revert_to_fdv1 = revert_to_fdv1
+          @fallback_to_fdv1 = fallback_to_fdv1
           @environment_id = environment_id
         end
+
+        # Deprecated alias retained for backwards compatibility while FDv2 is in early access.
+        # @deprecated Prefer {#fallback_to_fdv1}.
+        alias_method :revert_to_fdv1, :fallback_to_fdv1
       end
 
       #

lib/ldclient-rb/impl/data_system/fdv2.rb

@@ -214,8 +214,23 @@ def run_main_loop
               nil
             )
 
-            # Run initializers first
-            run_initializers
+            # Run initializers first. If an initializer signals the
+            # server-directed FDv1 Fallback Directive, switch terminally to
+            # the FDv1 Fallback Synchronizer (or transition to OFF if none
+            # is configured) before entering the synchronizer phase.
+            if run_initializers
+              if @fdv1_fallback_synchronizer_builder
+                @logger.warn { "[LDClient] Falling back to FDv1 protocol" }
+                @synchronizer_builders = [@fdv1_fallback_synchronizer_builder]
+              else
+                @logger.warn { "[LDClient] Initializer requested FDv1 fallback but none configured" }
+                @synchronizer_builders = []
+                @data_source_status_provider.update_status(
+                  LaunchDarkly::Interfaces::DataSource::Status::OFF,
+                  @data_source_status_provider.status.last_error
+                )
+              end
+            end
 
             # Run synchronizers
             run_synchronizers
@@ -228,39 +243,76 @@ def run_main_loop
         #
         # Run initializers to get initial data.
         #
-        # @return [void]
+        # Each initializer is tried in order until one succeeds, the system
+        # is stopped, or an initializer signals the server-directed FDv1
+        # Fallback Directive. When fallback is signalled alongside a valid
+        # payload, that payload is applied before returning so evaluations
+        # can serve the server-provided data while the FDv1 synchronizer
+        # spins up. The method returns true when fallback was requested so
+        # that the caller can switch the synchronizer list.
+        #
+        # @return [Boolean] true when an initializer requested FDv1 fallback.
         #
         def run_initializers
-          return unless @data_system_config.initializers
+          return false unless @data_system_config.initializers
 
           @data_system_config.initializers.each do |initializer_builder|
-            return if @stop_event.set?
+            return false if @stop_event.set?
 
             begin
               initializer = initializer_builder.build(@sdk_key, @config)
               @logger.info { "[LDClient] Attempting to initialize via #{initializer.name}" }
 
-              basis_result = initializer.fetch(@store)
+              fetch_result = initializer.fetch(@store)
+              fallback = fetch_result.respond_to?(:fallback_to_fdv1) && fetch_result.fallback_to_fdv1
+              # Support legacy implementations that return a bare Result.
+              basis_result = fetch_result.respond_to?(:result) ? fetch_result.result : fetch_result
 
               if basis_result.success?
                 basis = basis_result.value
                 @logger.info { "[LDClient] Initialized via #{initializer.name}" }
 
-                # Apply the basis to the store
+                # Apply the basis to the store regardless of whether
+                # fallback was signalled -- if the server returned a valid
+                # payload alongside the directive we still want evaluations
+                # to serve that data.
                 @store.apply(basis.change_set, basis.persist)
 
-                # Set ready event if and only if a selector is defined for the changeset
+                # Set ready event if and only if a selector is defined for the changeset.
+                # Even when fallback is requested, the payload that arrived with the directive
+                # has been applied to the store, so evaluations can serve it while the FDv1
+                # synchronizer spins up.
                 if basis.change_set.selector && basis.change_set.selector.defined?
                   @ready_event.set
-                  return
+                  return fallback ? true : false
                 end
               else
                 @logger.warn { "[LDClient] Initializer #{initializer.name} failed: #{basis_result.error}" }
+                if fallback
+                  # Record the underlying initializer error so that, if no FDv1 fallback is
+                  # configured, the subsequent transition to OFF carries it as last_error.
+                  @data_source_status_provider.update_status(
+                    LaunchDarkly::Interfaces::DataSource::Status::INITIALIZING,
+                    LaunchDarkly::Interfaces::DataSource::ErrorInfo.new(
+                      LaunchDarkly::Interfaces::DataSource::ErrorInfo::UNKNOWN,
+                      0,
+                      basis_result.error || "",
+                      Time.now
+                    )
+                  )
+                end
               end
+
+              # Honor the FDv1 Fallback Directive even on an error or undefined-selector path:
+              # the directive takes precedence over the regular failover algorithm, so we must
+              # not fall through to the next initializer.
+              return true if fallback
             rescue => e
               @logger.error { "[LDClient] Initializer failed with exception: #{e.message}" }
             end
           end
+
+          false
         end
 
         #
@@ -410,7 +462,7 @@ def consume_synchronizer_results(synchronizer, check_recovery: false)
               # Update status
               @data_source_status_provider.update_status(update.state, update.error)
 
-              return SyncResult::FDV1 if update.revert_to_fdv1
+              return SyncResult::FDV1 if update.fallback_to_fdv1
 
               return SyncResult::REMOVE if update.state == LaunchDarkly::Interfaces::DataSource::Status::OFF
             end

lib/ldclient-rb/impl/data_system/polling.rb

@@ -21,6 +21,18 @@ module DataSystem
       LD_ENVID_HEADER = "X-LD-EnvID"
       LD_FD_FALLBACK_HEADER = "X-LD-FD-Fallback"
 
+      #
+      # Reports whether the response headers signal that the SDK should fall
+      # back to the FDv1 protocol.
+      #
+      # @param headers [Hash, nil]
+      # @return [Boolean]
+      #
+      def self.fdv1_fallback_requested?(headers)
+        return false unless headers
+        headers[LD_FD_FALLBACK_HEADER] == 'true'
+      end
+
       #
       # PollingDataSource is a data source that can retrieve information from
       # LaunchDarkly either as an Initializer or as a Synchronizer.
@@ -46,10 +58,12 @@ def initialize(poll_interval, requester, logger)
         end
 
         #
-        # Fetch returns a Basis, or an error if the Basis could not be retrieved.
+        # Fetch returns a {LaunchDarkly::Interfaces::DataSystem::FetchResult}
+        # wrapping a Basis (or an error) and the FDv1 Fallback Directive
+        # signal carried on the server response.
         #
         # @param ss [LaunchDarkly::Interfaces::DataSystem::SelectorStore]
-        # @return [LaunchDarkly::Interfaces::DataSystem::Basis, nil]
+        # @return [LaunchDarkly::Interfaces::DataSystem::FetchResult]
         #
         def fetch(ss)
           poll(ss)
@@ -73,13 +87,8 @@ def sync(ss)
             result = @requester.fetch(ss.selector)
 
             if !result.success?
-              fallback = false
-              envid = nil
-
-              if result.headers
-                fallback = result.headers[LD_FD_FALLBACK_HEADER] == 'true'
-                envid = result.headers[LD_ENVID_HEADER]
-              end
+              fallback = LaunchDarkly::Impl::DataSystem.fdv1_fallback_requested?(result.headers)
+              envid = result.headers ? result.headers[LD_ENVID_HEADER] : nil
 
               if result.exception.is_a?(LaunchDarkly::Impl::DataSource::UnexpectedResponseError)
                 error_info = LaunchDarkly::Interfaces::DataSource::ErrorInfo.new(
@@ -99,7 +108,7 @@ def sync(ss)
                       state: LaunchDarkly::Interfaces::DataSource::Status::OFF,
                       error: error_info,
                       environment_id: envid,
-                      revert_to_fdv1: true
+                      fallback_to_fdv1: true
                     )
                     break
                   end
@@ -108,7 +117,7 @@ def sync(ss)
                     state: LaunchDarkly::Interfaces::DataSource::Status::INTERRUPTED,
                     error: error_info,
                     environment_id: envid,
-                    revert_to_fdv1: false
+                    fallback_to_fdv1: false
                   )
                   @interrupt_event.wait(@poll_interval)
                   next
@@ -118,7 +127,7 @@ def sync(ss)
                   state: LaunchDarkly::Interfaces::DataSource::Status::OFF,
                   error: error_info,
                   environment_id: envid,
-                  revert_to_fdv1: fallback
+                  fallback_to_fdv1: fallback
                 )
                 break
               end
@@ -136,7 +145,7 @@ def sync(ss)
                   state: LaunchDarkly::Interfaces::DataSource::Status::OFF,
                   error: error_info,
                   environment_id: envid,
-                  revert_to_fdv1: true
+                  fallback_to_fdv1: true
                 )
                 break
               end
@@ -145,16 +154,16 @@ def sync(ss)
                 state: LaunchDarkly::Interfaces::DataSource::Status::INTERRUPTED,
                 error: error_info,
                 environment_id: envid,
-                revert_to_fdv1: false
+                fallback_to_fdv1: false
               )
             else
               change_set, headers = result.value
-              fallback = headers[LD_FD_FALLBACK_HEADER] == 'true'
+              fallback = LaunchDarkly::Impl::DataSystem.fdv1_fallback_requested?(headers)
               yield LaunchDarkly::Interfaces::DataSystem::Update.new(
                 state: LaunchDarkly::Interfaces::DataSource::Status::VALID,
                 change_set: change_set,
                 environment_id: headers[LD_ENVID_HEADER],
-                revert_to_fdv1: fallback
+                fallback_to_fdv1: fallback
               )
             end
 
@@ -177,22 +186,39 @@ def stop
 
         #
         # @param ss [LaunchDarkly::Interfaces::DataSystem::SelectorStore]
-        # @return [LaunchDarkly::Result<LaunchDarkly::Interfaces::DataSystem::Basis, String>]
+        # @return [LaunchDarkly::Interfaces::DataSystem::FetchResult]
         #
         private def poll(ss)
           result = @requester.fetch(ss.selector)
 
+          # On success, the requester returns headers as the second element of the value tuple;
+          # on failure, headers ride on Result.headers. Check both so the fallback signal is
+          # surfaced regardless of outcome.
+          response_headers = nil
+          if result.success?
+            _, response_headers = result.value
+          else
+            response_headers = result.headers
+          end
+          fallback = LaunchDarkly::Impl::DataSystem.fdv1_fallback_requested?(response_headers)
+
           unless result.success?
             if result.exception.is_a?(LaunchDarkly::Impl::DataSource::UnexpectedResponseError)
               status_code = result.exception.status
               http_error_message_result = Impl::Util.http_error_message(
                 status_code, "polling request", "will retry"
               )
               @logger.warn { "[LDClient] #{http_error_message_result}" } if Impl::Util.http_error_recoverable?(status_code)
-              return LaunchDarkly::Result.fail(http_error_message_result, result.exception)
+              return LaunchDarkly::Interfaces::DataSystem::FetchResult.new(
+                result: LaunchDarkly::Result.fail(http_error_message_result, result.exception),
+                fallback_to_fdv1: fallback
+              )
             end
 
-            return LaunchDarkly::Result.fail(result.error || 'Failed to request payload', result.exception)
+            return LaunchDarkly::Interfaces::DataSystem::FetchResult.new(
+              result: LaunchDarkly::Result.fail(result.error || 'Failed to request payload', result.exception),
+              fallback_to_fdv1: fallback
+            )
           end
 
           change_set, headers = result.value
@@ -206,12 +232,18 @@ def stop
             environment_id: env_id
           )
 
-          LaunchDarkly::Result.success(basis)
+          LaunchDarkly::Interfaces::DataSystem::FetchResult.new(
+            result: LaunchDarkly::Result.success(basis),
+            fallback_to_fdv1: fallback
+          )
         rescue => e
           msg = "Error: Exception encountered when updating flags. #{e}"
           @logger.error { "[LDClient] #{msg}" }
           @logger.debug { "[LDClient] Exception trace: #{e.backtrace}" }
-          LaunchDarkly::Result.fail(msg, e)
+          LaunchDarkly::Interfaces::DataSystem::FetchResult.new(
+            result: LaunchDarkly::Result.fail(msg, e),
+            fallback_to_fdv1: false
+          )
         end
       end
 

lib/ldclient-rb/impl/data_system/streaming.rb

@@ -90,11 +90,11 @@ def sync(ss)
                 envid = headers[LD_ENVID_HEADER] || envid
 
                 # Check for fallback header on connection
-                if headers[LD_FD_FALLBACK_HEADER] == 'true'
+                if LaunchDarkly::Impl::DataSystem.fdv1_fallback_requested?(headers)
                   log_connection_result(true)
                   yield LaunchDarkly::Interfaces::DataSystem::Update.new(
                     state: LaunchDarkly::Interfaces::DataSource::Status::OFF,
-                    revert_to_fdv1: true,
+                    fallback_to_fdv1: true,
                     environment_id: envid
                   )
                   stop
@@ -150,10 +150,7 @@ def sync(ss)
               # Extract envid and fallback from error headers if available
               if error.respond_to?(:headers) && error.headers
                 envid = error.headers[LD_ENVID_HEADER] || envid
-
-                if error.headers[LD_FD_FALLBACK_HEADER] == 'true'
-                  fallback = true
-                end
+                fallback = true if LaunchDarkly::Impl::DataSystem.fdv1_fallback_requested?(error.headers)
               end
 
               update = handle_error(error, envid, fallback)
@@ -286,7 +283,7 @@ def stop
               update = LaunchDarkly::Interfaces::DataSystem::Update.new(
                 state: LaunchDarkly::Interfaces::DataSource::Status::OFF,
                 error: error_info,
-                revert_to_fdv1: true,
+                fallback_to_fdv1: true,
                 environment_id: envid
               )
               stop