launchdarkly-server-sdk 8.13.0 → 8.14.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6e2e62602bd745a9d90c6ab5c225c5e003f5a4e7aa83acc60305f6e16d6d1b46
-  data.tar.gz: 60be6f22178169195bb5cab7f6242ebc781361350ce5da18715395c5c6739258
+  metadata.gz: 30ec609a22208597d110a93cf4ea65b4b20a723cfccf5b3db743921aeb27a40a
+  data.tar.gz: 7833879176def90e31a71756cc27b90135985d2a75c305582ef3d09ad504ff72
 SHA512:
-  metadata.gz: '049b2d8a20a5be92e4a28bc2128c71f447ec94915a4a2c45a08260729a891609ee97e9a01e9a25e2ea2b3ddd7eda08fb3707276f8cc418afb1d401a66b08d2bb'
-  data.tar.gz: 7cf82c93c2bc5b6c6abbc63200f61cd5bc05d6b0cf8a780760e7ec4e86cf4ffccaff23b616f9496f3bbe614b20956f16adbfa83131040c68f1aee75ea1b80e6d
+  metadata.gz: c607be8b3926d090a243453c39375df4892c7ea49cb8a5f6c366bd47d4299c6f9ff525f2cb8e94c535b6a1dfa54a9f348ba4a59477e8eac8a420c1ce85fae777
+  data.tar.gz: 80d5b45d30922ce0c24f3ed56b7ca9f0e0d57e98e972600161b24517e89318da43fc94ba11219558467bf4e9088114b7b3b863b420ab0f9b1a88cc4f2805b018

data/README.md

@@ -43,7 +43,7 @@ We encourage pull requests and other contributions from the community. Check out
 Verifying SDK build provenance with the SLSA framework
 ------------
 
-LaunchDarkly uses the [SLSA framework](https://slsa.dev/spec/v1.0/about) (Supply-chain Levels for Software Artifacts) to help developers make their supply chain more secure by ensuring the authenticity and build integrity of our published SDK packages. To learn more, see the [provenance guide](PROVENANCE.md). 
+LaunchDarkly uses the [SLSA framework](https://slsa.dev/spec/v1.0/about) (Supply-chain Levels for Software Artifacts) to help developers make their supply chain more secure by ensuring the authenticity and build integrity of our published SDK packages. To learn more, see the [provenance guide](PROVENANCE.md).
 
 About LaunchDarkly
 -----------

data/lib/ldclient-rb/config.rb

@@ -697,9 +697,6 @@ module LaunchDarkly
   #
   # Configuration for LaunchDarkly's data acquisition strategy.
   #
-  # This is not stable and is not subject to any backwards compatibility guarantees
-  # or semantic versioning. It is not suitable for production usage.
-  #
   class DataSystemConfig
     #
     # @param initializers [Array<#build(String, Config)>, nil] The (optional) array of builders

data/lib/ldclient-rb/data_system/polling_data_source_builder.rb

@@ -21,9 +21,9 @@ module LaunchDarkly
     #     include LaunchDarkly::DataSystem::Requester
     #
     #     def fetch(selector)
-    #       # Fetch data and return a Result containing [ChangeSet, headers]
-    #       # ...
-    #       LaunchDarkly::Result.success([change_set, {}])
+    #       # Fetch data and return a Result whose value is a ChangeSet and
+    #       # whose headers carry any response metadata (e.g. directives).
+    #       LaunchDarkly::Result.success(change_set, response_headers)
     #     end
     #
     #     def stop
@@ -43,8 +43,10 @@ module LaunchDarkly
       # @param selector [LaunchDarkly::Interfaces::DataSystem::Selector, nil]
       #   The selector describing what data to fetch. May be nil if no
       #   selector is available (e.g., on the first request).
-      # @return [LaunchDarkly::Result] A Result containing a tuple of
-      #   [ChangeSet, headers] on success, or an error message on failure.
+      # @return [LaunchDarkly::Result] A Result whose `value` is a
+      #   {LaunchDarkly::Interfaces::DataSystem::ChangeSet} on success and
+      #   whose `headers` carry response headers in either case (so callers
+      #   can inspect directives such as `X-LD-FD-Fallback`).
       #
       def fetch(selector)
         raise NotImplementedError

data/lib/ldclient-rb/impl/data_store/feature_store_client_wrapper.rb

@@ -65,6 +65,18 @@ module LaunchDarkly
           @store.initialized?
         end
 
+        #
+        # Passthrough for the FDv2 store coordinator. If the wrapped store supports
+        # disabling its cache (e.g. {LaunchDarkly::Integrations::Util::CachingStoreWrapper}),
+        # forward the call; otherwise no-op.
+        #
+        # @return [void]
+        #
+        def disable_cache
+          return unless @store.respond_to?(:disable_cache)
+          wrapper { @store.disable_cache }
+        end
+
         # (see LaunchDarkly::Interfaces::FeatureStore#stop)
         def stop
           poller_to_stop = nil

data/lib/ldclient-rb/impl/data_store/store.rb

@@ -221,6 +221,12 @@ module LaunchDarkly
           # Switch to memory store as active
           @active_store = @memory_store
 
+          # In-memory store is now authoritative. Disable the persistent-store cache
+          # so we don't hold a duplicate copy of every flag. Done before the
+          # persistent_store.init below so the wrapper can skip its cache-population
+          # loop on this very call.
+          disable_persistent_cache
+
           # Persist to persistent store if configured and writable
           @persistent_store.init(collections) if should_persist?
 
@@ -271,6 +277,24 @@ module LaunchDarkly
           send_change_events(affected_items) unless affected_items.empty?
         end
 
+        #
+        # Disable the persistent store's in-memory cache, if it has one. The FDv2 in-memory
+        # store is now the source of truth, so the cache is dead weight and would just
+        # hold a duplicate copy of every flag.
+        #
+        # @return [void]
+        #
+        private def disable_persistent_cache
+          return if @persistent_store.nil?
+          return unless @persistent_store.respond_to?(:disable_cache)
+
+          begin
+            @persistent_store.disable_cache
+          rescue => e
+            @logger.warn { "[LDClient] Failed to disable persistent store cache: #{e.message}" }
+          end
+        end
+
         #
         # Returns whether data should be persisted to the persistent store.
         #

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

@@ -214,8 +214,23 @@ module LaunchDarkly
               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,70 @@ module LaunchDarkly
         #
         # 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.fallback_to_fdv1
+              basis_result = fetch_result.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 while the FDv1 synchronizer spins up.
                 @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.
                 if basis.change_set.selector && basis.change_set.selector.defined?
                   @ready_event.set
-                  return
+                  return fallback
                 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
+
+              # The fallback directive takes precedence over the regular failover algorithm,
+              # so do not fall through to the next initializer when it is set.
+              return true if fallback
             rescue => e
               @logger.error { "[LDClient] Initializer failed with exception: #{e.message}" }
             end
           end
+
+          false
         end
 
         #
@@ -313,12 +359,21 @@ module LaunchDarkly
                 case sync_result
                 when SyncResult::FDV1
                   if @fdv1_fallback_synchronizer_builder
+                    @logger.warn { "[LDClient] Falling back to FDv1 protocol" }
                     @synchronizer_builders = [@fdv1_fallback_synchronizer_builder]
                     current_index = 0
                     next
                   end
-                  # No FDv1 fallback configured, treat as regular fallback
-                  current_index += 1
+                  # No FDv1 fallback configured: the data system must HALT
+                  # rather than fall through to the next FDv2 synchronizer.
+                  # Continuing to retry would reopen the connection that just
+                  # delivered the directive.
+                  @logger.warn { "[LDClient] Synchronizer requested FDv1 fallback but none configured; halting data system" }
+                  @data_source_status_provider.update_status(
+                    LaunchDarkly::Interfaces::DataSource::Status::OFF,
+                    @data_source_status_provider.status.last_error
+                  )
+                  break
                 when SyncResult::RECOVER
                   @logger.info { "[LDClient] Recovery condition met, returning to primary synchronizer" }
                   current_index = 0
@@ -410,7 +465,7 @@ module LaunchDarkly
               # 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

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

@@ -21,6 +21,60 @@ module LaunchDarkly
       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. Lookup is case-insensitive so callers do
+      # not need to know whether the header map preserves canonical casing
+      # (e.g. {HTTP::Headers}) or has been normalized to lowercase (e.g.
+      # {HTTPPollingRequester#fetch}).
+      #
+      # @param headers [#[], Hash, nil]
+      # @return [Boolean]
+      #
+      def self.fdv1_fallback_requested?(headers)
+        return false if headers.nil?
+        value = lookup_header(headers, LD_FD_FALLBACK_HEADER)
+        # http gem returns arrays for repeated headers; normalize to a string.
+        value = value.first if value.is_a?(Array)
+        value == 'true'
+      end
+
+      #
+      # Performs a case-insensitive header lookup that works with both
+      # case-insensitive header containers (e.g. `HTTP::Headers`) and plain
+      # Ruby hashes -- including hashes whose keys we have downcased
+      # ourselves before reaching this code path.
+      #
+      # @param headers [#[], Hash]
+      # @param name [String]
+      # @return [String, Array, nil]
+      #
+      def self.lookup_header(headers, name)
+        return nil if headers.nil?
+
+        if headers.is_a?(Hash)
+          # Plain hash: try canonical case, then exact lowercase, then a
+          # case-insensitive scan as a final fallback.
+          value = headers[name]
+          return value unless value.nil?
+
+          downcased = name.downcase
+          value = headers[downcased]
+          return value unless value.nil?
+
+          headers.each_pair do |key, val|
+            return val if key.to_s.downcase == downcased
+          end
+          return nil
+        end
+
+        # Non-hash container (e.g. HTTP::Headers). Lookup via [] is
+        # already case-insensitive on those types.
+        return headers[name] if headers.respond_to?(:[])
+
+        nil
+      end
+
       #
       # PollingDataSource is a data source that can retrieve information from
       # LaunchDarkly either as an Initializer or as a Synchronizer.
@@ -46,10 +100,12 @@ module LaunchDarkly
         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)
@@ -71,16 +127,10 @@ module LaunchDarkly
 
           until @stop.set?
             result = @requester.fetch(ss.selector)
+            fallback = LaunchDarkly::Impl::DataSystem.fdv1_fallback_requested?(result.headers)
+            envid = LaunchDarkly::Impl::DataSystem.lookup_header(result.headers, LD_ENVID_HEADER)
 
             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
-
               if result.exception.is_a?(LaunchDarkly::Impl::DataSource::UnexpectedResponseError)
                 error_info = LaunchDarkly::Interfaces::DataSource::ErrorInfo.new(
                   LaunchDarkly::Interfaces::DataSource::ErrorInfo::ERROR_RESPONSE,
@@ -99,7 +149,7 @@ module LaunchDarkly
                       state: LaunchDarkly::Interfaces::DataSource::Status::OFF,
                       error: error_info,
                       environment_id: envid,
-                      revert_to_fdv1: true
+                      fallback_to_fdv1: true
                     )
                     break
                   end
@@ -108,7 +158,7 @@ module LaunchDarkly
                     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 +168,7 @@ module LaunchDarkly
                   state: LaunchDarkly::Interfaces::DataSource::Status::OFF,
                   error: error_info,
                   environment_id: envid,
-                  revert_to_fdv1: fallback
+                  fallback_to_fdv1: fallback
                 )
                 break
               end
@@ -136,7 +186,7 @@ module LaunchDarkly
                   state: LaunchDarkly::Interfaces::DataSource::Status::OFF,
                   error: error_info,
                   environment_id: envid,
-                  revert_to_fdv1: true
+                  fallback_to_fdv1: true
                 )
                 break
               end
@@ -145,16 +195,14 @@ module LaunchDarkly
                 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'
               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
+                change_set: result.value,
+                environment_id: envid,
+                fallback_to_fdv1: fallback
               )
             end
 
@@ -177,10 +225,14 @@ module LaunchDarkly
 
         #
         # @param ss [LaunchDarkly::Interfaces::DataSystem::SelectorStore]
-        # @return [LaunchDarkly::Result<LaunchDarkly::Interfaces::DataSystem::Basis, String>]
+        # @return [LaunchDarkly::Interfaces::DataSystem::FetchResult]
         #
         private def poll(ss)
+          # Default to false so the rescue clause has a defined value even when an
+          # exception is raised before the header read below has had a chance to run.
+          fallback = false
           result = @requester.fetch(ss.selector)
+          fallback = LaunchDarkly::Impl::DataSystem.fdv1_fallback_requested?(result.headers)
 
           unless result.success?
             if result.exception.is_a?(LaunchDarkly::Impl::DataSource::UnexpectedResponseError)
@@ -189,15 +241,20 @@ module LaunchDarkly
                 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
-
-          env_id = headers[LD_ENVID_HEADER]
+          change_set = result.value
+          env_id = LaunchDarkly::Impl::DataSystem.lookup_header(result.headers, LD_ENVID_HEADER)
           env_id = nil unless env_id.is_a?(String)
 
           basis = LaunchDarkly::Interfaces::DataSystem::Basis.new(
@@ -206,12 +263,22 @@ module LaunchDarkly
             environment_id: env_id
           )
 
-          LaunchDarkly::Result.success(basis)
+          LaunchDarkly::Interfaces::DataSystem::FetchResult.new(
+            result: LaunchDarkly::Result.success(basis),
+            fallback_to_fdv1: fallback
+          )
         rescue => e
+          # An exception can fire after we have already read the response
+          # headers (e.g. a malformed change_set whose selector is nil makes
+          # change_set.selector.defined? raise). Carry the computed fallback
+          # signal through so the directive is not silently dropped.
           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: fallback
+          )
         end
       end
 
@@ -273,7 +340,7 @@ module LaunchDarkly
             end
 
             if status == 304
-              return LaunchDarkly::Result.success([LaunchDarkly::Interfaces::DataSystem::ChangeSetBuilder.no_changes, response_headers])
+              return LaunchDarkly::Result.success(LaunchDarkly::Interfaces::DataSystem::ChangeSetBuilder.no_changes, response_headers)
             end
 
             body = response.to_s
@@ -285,7 +352,7 @@ module LaunchDarkly
 
             changeset_result = LaunchDarkly::Impl::DataSystem.polling_payload_to_changeset(data)
             if changeset_result.success?
-              LaunchDarkly::Result.success([changeset_result.value, response_headers])
+              LaunchDarkly::Result.success(changeset_result.value, response_headers)
             else
               LaunchDarkly::Result.fail(changeset_result.error, changeset_result.exception, response_headers)
             end
@@ -361,7 +428,7 @@ module LaunchDarkly
             end
 
             if status == 304
-              return LaunchDarkly::Result.success([LaunchDarkly::Interfaces::DataSystem::ChangeSetBuilder.no_changes, response_headers])
+              return LaunchDarkly::Result.success(LaunchDarkly::Interfaces::DataSystem::ChangeSetBuilder.no_changes, response_headers)
             end
 
             body = response.to_s
@@ -373,7 +440,7 @@ module LaunchDarkly
 
             changeset_result = LaunchDarkly::Impl::DataSystem.fdv1_polling_payload_to_changeset(data)
             if changeset_result.success?
-              LaunchDarkly::Result.success([changeset_result.value, response_headers])
+              LaunchDarkly::Result.success(changeset_result.value, response_headers)
             else
               LaunchDarkly::Result.fail(changeset_result.error, changeset_result.exception, response_headers)
             end

data/lib/ldclient-rb/impl/data_system/protocolv2.rb

@@ -12,9 +12,6 @@ module LaunchDarkly
         #
         # DeleteObject specifies the deletion of a particular object.
         #
-        # This type is not stable, and not subject to any backwards
-        # compatibility guarantees or semantic versioning. It is not suitable for production usage.
-        #
         class DeleteObject
           # @return [Integer] The version
           attr_reader :version
@@ -79,9 +76,6 @@ module LaunchDarkly
         #
         # PutObject specifies the addition of a particular object with upsert semantics.
         #
-        # This type is not stable, and not subject to any backwards
-        # compatibility guarantees or semantic versioning. It is not suitable for production usage.
-        #
         class PutObject
           # @return [Integer] The version
           attr_reader :version
@@ -153,28 +147,15 @@ module LaunchDarkly
         #
         # Goodbye represents a goodbye event.
         #
-        # This type is not stable, and not subject to any backwards
-        # compatibility guarantees or semantic versioning. It is not suitable for production usage.
-        #
         class Goodbye
           # @return [String] The reason for goodbye
           attr_reader :reason
 
-          # @return [Boolean] Whether the goodbye is silent
-          attr_reader :silent
-
-          # @return [Boolean] Whether this represents a catastrophic failure
-          attr_reader :catastrophe
-
           #
           # @param reason [String] The reason for goodbye
-          # @param silent [Boolean] Whether the goodbye is silent
-          # @param catastrophe [Boolean] Whether this represents a catastrophic failure
           #
-          def initialize(reason:, silent:, catastrophe:)
+          def initialize(reason:)
             @reason = reason
-            @silent = silent
-            @catastrophe = catastrophe
           end
 
           #
@@ -185,8 +166,6 @@ module LaunchDarkly
           def to_h
             {
               reason: @reason,
-              silent: @silent,
-              catastrophe: @catastrophe,
             }
           end
 
@@ -199,21 +178,16 @@ module LaunchDarkly
           #
           def self.from_h(data)
             reason = data[:reason]
-            silent = data[:silent]
-            catastrophe = data[:catastrophe]
 
-            raise ArgumentError, "Missing required fields in Goodbye" if reason.nil? || silent.nil? || catastrophe.nil?
+            raise ArgumentError, "Missing required fields in Goodbye" if reason.nil?
 
-            new(reason: reason, silent: silent, catastrophe: catastrophe)
+            new(reason: reason)
           end
         end
 
         #
         # Error represents an error event.
         #
-        # This type is not stable, and not subject to any backwards
-        # compatibility guarantees or semantic versioning. It is not suitable for production usage.
-        #
         class Error
           # @return [String] The payload ID
           attr_reader :payload_id