launchdarkly-server-sdk 8.13.0 → 8.14.0

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

@@ -72,6 +72,25 @@ module LaunchDarkly
 
           change_set_builder = LaunchDarkly::Interfaces::DataSystem::ChangeSetBuilder.new
           envid = nil
+          # The FDv1 Fallback Directive is one-way and terminal: once any
+          # connect handshake within this sync invocation carries it, the SDK
+          # is committed to engaging FDv1 as soon as the next full payload
+          # has been applied. We therefore latch this flag to true on first
+          # observation and never reset it -- a mid-sync reconnect whose
+          # response no longer carries the directive does NOT cancel a
+          # directive seen earlier. This matches the Go and Python SDK
+          # implementations, both of which use the same latch pattern.
+          #
+          # The flag has to bridge two callbacks: on_connect sees the response
+          # headers but on_event does not. A local closed over by both blocks
+          # is correct because:
+          #   1. Scope -- bound to a single sync invocation, so a future sync
+          #      starts fresh. (Within this invocation, persistence across
+          #      reconnects is the intended semantics, per above.)
+          #   2. Thread safety -- ld-eventsource dispatches on_connect,
+          #      on_event, and on_error on the same SSE worker thread, so
+          #      reads and writes here are single-threaded by construction.
+          fdv1_fallback_pending = false
 
           base_uri = @http_config.base_uri + FDV2_STREAMING_ENDPOINT
           headers = Impl::Util.default_http_headers(@sdk_key, @config)
@@ -85,30 +104,32 @@ module LaunchDarkly
 
           @sse = SSE::Client.new(base_uri, **opts) do |client|
             client.on_connect do |headers|
-              # Extract environment ID and check for fallback on successful connection
               if headers
-                envid = headers[LD_ENVID_HEADER] || envid
-
-                # Check for fallback header on connection
-                if headers[LD_FD_FALLBACK_HEADER] == 'true'
-                  log_connection_result(true)
-                  yield LaunchDarkly::Interfaces::DataSystem::Update.new(
-                    state: LaunchDarkly::Interfaces::DataSource::Status::OFF,
-                    revert_to_fdv1: true,
-                    environment_id: envid
-                  )
-                  stop
-                end
+                # Per-environment identifier: server sends it on every connect,
+                # but it never changes once known so only assign once.
+                envid ||= LaunchDarkly::Impl::DataSystem.lookup_header(headers, LD_ENVID_HEADER)
+                fdv1_fallback_pending = true if LaunchDarkly::Impl::DataSystem.fdv1_fallback_requested?(headers)
               end
             end
 
             client.on_event do |event|
               begin
-                update = process_message(event, change_set_builder, envid)
-                if update
-                  log_connection_result(true)
-                  @connection_attempt_start_time = 0
-                  yield update
+                update = process_message(event, change_set_builder, envid, fdv1_fallback_pending: fdv1_fallback_pending)
+                next unless update
+
+                log_connection_result(true)
+                @connection_attempt_start_time = 0
+
+                yield update
+
+                # When the FDv1 Fallback Directive rode along on a Valid update, close
+                # the stream so the primary synchronizer is stopped once the directive
+                # engages. process_message marks the Update with fallback_to_fdv1 only
+                # on payloads that complete a transfer, so the consumer has already
+                # applied the ChangeSet by the time we get here.
+                if update.fallback_to_fdv1
+                  fdv1_fallback_pending = false
+                  stop
                 end
               rescue JSON::ParserError => e
                 @logger.info { "[LDClient] Error parsing stream event; will restart stream: #{e}" }
@@ -147,13 +168,9 @@ module LaunchDarkly
               log_connection_result(false)
               fallback = false
 
-              # 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
+                envid ||= LaunchDarkly::Impl::DataSystem.lookup_header(error.headers, LD_ENVID_HEADER)
+                fallback = true if LaunchDarkly::Impl::DataSystem.fdv1_fallback_requested?(error.headers)
               end
 
               update = handle_error(error, envid, fallback)
@@ -193,9 +210,15 @@ module LaunchDarkly
         # @param message [SSE::StreamEvent]
         # @param change_set_builder [LaunchDarkly::Interfaces::DataSystem::ChangeSetBuilder]
         # @param envid [String, nil]
+        # @param fdv1_fallback_pending [Boolean] true when the connect-time
+        #   response headers carried the FDv1 Fallback Directive. When set,
+        #   the next Update that completes a payload transfer (TRANSFER_NONE
+        #   or PAYLOAD_TRANSFERRED) is marked with fallback_to_fdv1: true so
+        #   the consumer can engage the FDv1 Fallback Synchronizer after
+        #   applying the in-flight ChangeSet.
         # @return [LaunchDarkly::Interfaces::DataSystem::Update, nil]
         #
-        private def process_message(message, change_set_builder, envid)
+        private def process_message(message, change_set_builder, envid, fdv1_fallback_pending: false)
           event_type = message.type
 
           # Handle heartbeat
@@ -214,7 +237,8 @@ module LaunchDarkly
               change_set_builder.expect_changes
               return LaunchDarkly::Interfaces::DataSystem::Update.new(
                 state: LaunchDarkly::Interfaces::DataSource::Status::VALID,
-                environment_id: envid
+                environment_id: envid,
+                fallback_to_fdv1: fdv1_fallback_pending
               )
             end
             nil
@@ -231,9 +255,7 @@ module LaunchDarkly
 
           when LaunchDarkly::Interfaces::DataSystem::EventName::GOODBYE
             goodbye = LaunchDarkly::Impl::DataSystem::ProtocolV2::Goodbye.from_h(JSON.parse(message.data, symbolize_names: true))
-            unless goodbye.silent
-              @logger.error { "[LDClient] SSE server received error: #{goodbye.reason} (catastrophe: #{goodbye.catastrophe})" }
-            end
+            @logger.info { "[LDClient] SSE server received goodbye: #{goodbye.reason}" }
             nil
 
           when LaunchDarkly::Interfaces::DataSystem::EventName::ERROR
@@ -251,7 +273,8 @@ module LaunchDarkly
             LaunchDarkly::Interfaces::DataSystem::Update.new(
               state: LaunchDarkly::Interfaces::DataSource::Status::VALID,
               change_set: change_set,
-              environment_id: envid
+              environment_id: envid,
+              fallback_to_fdv1: fdv1_fallback_pending
             )
 
           else
@@ -286,7 +309,7 @@ module LaunchDarkly
               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

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

@@ -247,8 +247,9 @@ module LaunchDarkly
         # @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,14 +258,14 @@ module LaunchDarkly
         # @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
       end

data/lib/ldclient-rb/impl/integrations/file_data_source_v2.rb

@@ -71,31 +71,38 @@ module LaunchDarkly
         # Implementation of the Initializer.fetch method.
         #
         # Reads all configured files once and returns their contents as a Basis.
+        # File-based data sources never request the FDv1 Fallback Directive,
+        # so the returned {FetchResult} always reports `fallback_to_fdv1: false`.
         #
         # @param selector_store [LaunchDarkly::Interfaces::DataSystem::SelectorStore] Provides the Selector (unused for file data)
-        # @return [LaunchDarkly::Result] A Result containing either a Basis or an error message
+        # @return [LaunchDarkly::Interfaces::DataSystem::FetchResult]
         #
         def fetch(selector_store)
-          @lock.synchronize do
-            if @closed
-              return LaunchDarkly::Result.fail('FileDataV2 source has been closed')
-            end
+          result =
+            begin
+              @lock.synchronize do
+                if @closed
+                  next LaunchDarkly::Result.fail('FileDataV2 source has been closed')
+                end
 
-            result = load_all_to_changeset
-            return result unless result.success?
+                load_result = load_all_to_changeset
+                next load_result unless load_result.success?
 
-            change_set = result.value
-            basis = LaunchDarkly::Interfaces::DataSystem::Basis.new(
-              change_set: change_set,
-              persist: false,
-              environment_id: nil
-            )
+                change_set = load_result.value
+                basis = LaunchDarkly::Interfaces::DataSystem::Basis.new(
+                  change_set: change_set,
+                  persist: false,
+                  environment_id: nil
+                )
 
-            LaunchDarkly::Result.success(basis)
-          end
-        rescue => e
-          @logger.error { "[LDClient] Error fetching file data: #{e.message}" }
-          LaunchDarkly::Result.fail("Error fetching file data: #{e.message}", e)
+                LaunchDarkly::Result.success(basis)
+              end
+            rescue => e
+              @logger.error { "[LDClient] Error fetching file data: #{e.message}" }
+              LaunchDarkly::Result.fail("Error fetching file data: #{e.message}", e)
+            end
+
+          LaunchDarkly::Interfaces::DataSystem::FetchResult.new(result: result, fallback_to_fdv1: false)
         end
 
         #
@@ -110,14 +117,14 @@ module LaunchDarkly
         #
         def sync(selector_store)
           # First yield initial data
-          initial_result = fetch(selector_store)
-          unless initial_result.success?
+          initial_fetch = fetch(selector_store)
+          unless initial_fetch.success?
             yield LaunchDarkly::Interfaces::DataSystem::Update.new(
               state: LaunchDarkly::Interfaces::DataSource::Status::OFF,
               error: LaunchDarkly::Interfaces::DataSource::ErrorInfo.new(
                 LaunchDarkly::Interfaces::DataSource::ErrorInfo::INVALID_DATA,
                 0,
-                initial_result.error,
+                initial_fetch.error,
                 Time.now
               )
             )
@@ -126,7 +133,7 @@ module LaunchDarkly
 
           yield LaunchDarkly::Interfaces::DataSystem::Update.new(
             state: LaunchDarkly::Interfaces::DataSource::Status::VALID,
-            change_set: initial_result.value.change_set
+            change_set: initial_fetch.value.change_set
           )
 
           # Start watching for file changes

data/lib/ldclient-rb/impl/integrations/redis_impl.rb

@@ -93,6 +93,10 @@ module LaunchDarkly
           def stop
             @wrapper.stop
           end
+
+          def disable_cache
+            @wrapper.disable_cache
+          end
         end
 
         class RedisStoreImplBase

data/lib/ldclient-rb/impl/integrations/test_data/test_data_source_v2.rb

@@ -46,56 +46,61 @@ module LaunchDarkly
           # Implementation of the Initializer.fetch method.
           #
           # Returns the current test data as a Basis for initial data loading.
+          # Test data sources never request the FDv1 Fallback Directive, so the
+          # returned {FetchResult} always reports `fallback_to_fdv1: false`.
           #
           # @param selector_store [LaunchDarkly::Interfaces::DataSystem::SelectorStore] Provides the Selector (unused for test data)
-          # @return [LaunchDarkly::Result] A Result containing either a Basis or an error message
+          # @return [LaunchDarkly::Interfaces::DataSystem::FetchResult]
           #
           def fetch(selector_store)
-            begin
-              @lock.synchronize do
-                if @closed
-                  return LaunchDarkly::Result.fail('TestDataV2 source has been closed')
-                end
-
-                # Get all current flags and segments from test data
-                init_data = @test_data.make_init_data
-                version = @test_data.get_version
-
-                # Build a full transfer changeset
-                builder = LaunchDarkly::Interfaces::DataSystem::ChangeSetBuilder.new
-                builder.start(LaunchDarkly::Interfaces::DataSystem::IntentCode::TRANSFER_FULL)
-
-                # Add all flags to the changeset
-                init_data[:flags].each do |key, flag_data|
-                  builder.add_put(
-                    LaunchDarkly::Interfaces::DataSystem::ObjectKind::FLAG,
-                    key,
-                    flag_data[:version] || 1,
-                    flag_data
-                  )
-                end
-
-                # Add all segments to the changeset
-                init_data[:segments].each do |key, segment_data|
-                  builder.add_put(
-                    LaunchDarkly::Interfaces::DataSystem::ObjectKind::SEGMENT,
-                    key,
-                    segment_data[:version] || 1,
-                    segment_data
-                  )
+            result =
+              begin
+                @lock.synchronize do
+                  if @closed
+                    next LaunchDarkly::Result.fail('TestDataV2 source has been closed')
+                  end
+
+                  # Get all current flags and segments from test data
+                  init_data = @test_data.make_init_data
+                  version = @test_data.get_version
+
+                  # Build a full transfer changeset
+                  builder = LaunchDarkly::Interfaces::DataSystem::ChangeSetBuilder.new
+                  builder.start(LaunchDarkly::Interfaces::DataSystem::IntentCode::TRANSFER_FULL)
+
+                  # Add all flags to the changeset
+                  init_data[:flags].each do |key, flag_data|
+                    builder.add_put(
+                      LaunchDarkly::Interfaces::DataSystem::ObjectKind::FLAG,
+                      key,
+                      flag_data[:version] || 1,
+                      flag_data
+                    )
+                  end
+
+                  # Add all segments to the changeset
+                  init_data[:segments].each do |key, segment_data|
+                    builder.add_put(
+                      LaunchDarkly::Interfaces::DataSystem::ObjectKind::SEGMENT,
+                      key,
+                      segment_data[:version] || 1,
+                      segment_data
+                    )
+                  end
+
+                  # Create selector for this version
+                  selector = LaunchDarkly::Interfaces::DataSystem::Selector.new_selector(version.to_s, version)
+                  change_set = builder.finish(selector)
+
+                  basis = LaunchDarkly::Interfaces::DataSystem::Basis.new(change_set: change_set, persist: false, environment_id: nil)
+
+                  LaunchDarkly::Result.success(basis)
                 end
-
-                # Create selector for this version
-                selector = LaunchDarkly::Interfaces::DataSystem::Selector.new_selector(version.to_s, version)
-                change_set = builder.finish(selector)
-
-                basis = LaunchDarkly::Interfaces::DataSystem::Basis.new(change_set: change_set, persist: false, environment_id: nil)
-
-                LaunchDarkly::Result.success(basis)
+              rescue => e
+                LaunchDarkly::Result.fail("Error fetching test data: #{e.message}", e)
               end
-            rescue => e
-              LaunchDarkly::Result.fail("Error fetching test data: #{e.message}", e)
-            end
+
+            LaunchDarkly::Interfaces::DataSystem::FetchResult.new(result: result, fallback_to_fdv1: false)
           end
 
           #
@@ -109,14 +114,14 @@ module LaunchDarkly
           #
           def sync(selector_store)
             # First yield initial data
-            initial_result = fetch(selector_store)
-            unless initial_result.success?
+            initial_fetch = fetch(selector_store)
+            unless initial_fetch.success?
               yield LaunchDarkly::Interfaces::DataSystem::Update.new(
                 state: LaunchDarkly::Interfaces::DataSource::Status::OFF,
                 error: LaunchDarkly::Interfaces::DataSource::ErrorInfo.new(
                   LaunchDarkly::Interfaces::DataSource::ErrorInfo::STORE_ERROR,
                   0,
-                  initial_result.error,
+                  initial_fetch.error,
                   Time.now
                 )
               )
@@ -126,7 +131,7 @@ module LaunchDarkly
             # Yield the initial successful state
             yield LaunchDarkly::Interfaces::DataSystem::Update.new(
               state: LaunchDarkly::Interfaces::DataSource::Status::VALID,
-              change_set: initial_result.value.change_set
+              change_set: initial_fetch.value.change_set
             )
 
             # Continue yielding updates as they arrive

data/lib/ldclient-rb/integrations/consul.rb

@@ -32,8 +32,12 @@ module LaunchDarkly
       # @option opts [String] :url   shortcut for setting the `url` property of the Consul client configuration
       # @option opts [String] :prefix  namespace prefix to add to all keys used by LaunchDarkly
       # @option opts [Logger] :logger  a `Logger` instance; defaults to `Config.default_logger`
-      # @option opts [Integer] :expiration (15)  expiration time for the in-memory cache, in seconds; 0 for no local caching
-      # @option opts [Integer] :capacity (1000)  maximum number of items in the cache
+      # @option opts [Integer] :expiration (15)  expiration time for the in-memory cache, in seconds; 0 for no local caching.
+      #   When the SDK is configured to use FDv2, the persistent-store cache is automatically
+      #   dropped once the in-memory store has been initialized, so this setting only affects
+      #   the brief bootstrap window before the first set of flag data has been received.
+      # @option opts [Integer] :capacity (1000)  maximum number of items in the cache.
+      #   Same FDv2 caveat as `:expiration` applies.
       # @return [LaunchDarkly::Interfaces::FeatureStore]  a feature store object
       #
       def self.new_feature_store(opts = {})

data/lib/ldclient-rb/integrations/dynamodb.rb

@@ -42,8 +42,12 @@ module LaunchDarkly
       # @option opts [Object] :existing_client  an already-constructed DynamoDB client for the feature store to use
       # @option opts [String] :prefix  namespace prefix to add to all keys used by LaunchDarkly
       # @option opts [Logger] :logger  a `Logger` instance; defaults to `Config.default_logger`
-      # @option opts [Integer] :expiration (15)  expiration time for the in-memory cache, in seconds; 0 for no local caching
-      # @option opts [Integer] :capacity (1000)  maximum number of items in the cache
+      # @option opts [Integer] :expiration (15)  expiration time for the in-memory cache, in seconds; 0 for no local caching.
+      #   When the SDK is configured to use FDv2, the persistent-store cache is automatically
+      #   dropped once the in-memory store has been initialized, so this setting only affects
+      #   the brief bootstrap window before the first set of flag data has been received.
+      # @option opts [Integer] :capacity (1000)  maximum number of items in the cache.
+      #   Same FDv2 caveat as `:expiration` applies.
       # @return [LaunchDarkly::Interfaces::FeatureStore]  a feature store object
       #
       def self.new_feature_store(table_name, opts = {})

data/lib/ldclient-rb/integrations/file_data.rb

@@ -108,9 +108,6 @@ module LaunchDarkly
       #
       # Returns a builder for the FDv2-compatible file data source.
       #
-      # This method is not stable, and not subject to any backwards compatibility guarantees or semantic versioning.
-      # It is in early access. If you want access to this feature please join the EAP. https://launchdarkly.com/docs/sdk/features/data-saving-mode
-      #
       # This method returns a builder proc that can be used with the FDv2 data system
       # configuration as both an Initializer and a Synchronizer. When used as an Initializer
       # (via `fetch`), it reads files once. When used as a Synchronizer (via `sync`), it

data/lib/ldclient-rb/integrations/redis.rb

@@ -50,8 +50,12 @@ module LaunchDarkly
       # @option opts [String] :prefix (default_prefix)  namespace prefix to add to all hash keys used by LaunchDarkly
       # @option opts [Logger] :logger  a `Logger` instance; defaults to `Config.default_logger`
       # @option opts [Integer] :max_connections  size of the Redis connection pool
-      # @option opts [Integer] :expiration (15)  expiration time for the in-memory cache, in seconds; 0 for no local caching
-      # @option opts [Integer] :capacity (1000)  maximum number of items in the cache
+      # @option opts [Integer] :expiration (15)  expiration time for the in-memory cache, in seconds; 0 for no local caching.
+      #   When the SDK is configured to use FDv2, the persistent-store cache is automatically
+      #   dropped once the in-memory store has been initialized, so this setting only affects
+      #   the brief bootstrap window before the first set of flag data has been received.
+      # @option opts [Integer] :capacity (1000)  maximum number of items in the cache.
+      #   Same FDv2 caveat as `:expiration` applies.
       # @option opts [Object] :pool  custom connection pool, if desired
       # @option opts [Boolean] :pool_shutdown_on_close whether calling `close` should shutdown the custom connection pool;
       #   this is true by default, and should be set to false only if you are managing the pool yourself and want its

data/lib/ldclient-rb/integrations/test_data_v2.rb

@@ -9,9 +9,6 @@ module LaunchDarkly
     # A mechanism for providing dynamically updatable feature flag state in a
     # simplified form to an SDK client in test scenarios using the FDv2 protocol.
     #
-    # This class is not stable, and not subject to any backwards compatibility guarantees or semantic versioning.
-    # It is in early access. If you want access to this feature please join the EAP. https://launchdarkly.com/docs/sdk/features/data-saving-mode
-    #
     # Unlike {LaunchDarkly::Integrations::FileData}, this mechanism does not use any external resources. It
     # provides only the data that the application has put into it using the {#update} method.
     #

data/lib/ldclient-rb/integrations/util/store_wrapper.rb

@@ -61,50 +61,52 @@ module LaunchDarkly
           @core.init_internal(all_data)
           @inited.make_true
 
-          unless @cache.nil?
-            @cache.clear
+          cache = @cache
+          unless cache.nil?
+            cache.clear
             all_data.each do |kind, items|
-              @cache[kind] = items_if_not_deleted(items)
+              cache[kind] = items_if_not_deleted(items)
               items.each do |key, item|
-                @cache[item_cache_key(kind, key)] = [item]
+                cache[item_cache_key(kind, key)] = [item]
               end
             end
           end
         end
 
         def get(kind, key)
-          unless @cache.nil?
-            cache_key = item_cache_key(kind, key)
-            cached = @cache[cache_key] # note, item entries in the cache are wrapped in an array so we can cache nil values
+          cache = @cache
+          cache_key = item_cache_key(kind, key)
+          unless cache.nil?
+            cached = cache[cache_key] # note, item entries in the cache are wrapped in an array so we can cache nil values
             return item_if_not_deleted(cached[0]) unless cached.nil?
           end
 
           item = @core.get_internal(kind, key)
 
-          unless @cache.nil?
-            @cache[cache_key] = [item]
-          end
+          cache[cache_key] = [item] unless cache.nil?
 
           item_if_not_deleted(item)
         end
 
         def all(kind)
-          unless @cache.nil?
-            items = @cache[all_cache_key(kind)]
+          cache = @cache
+          unless cache.nil?
+            items = cache[all_cache_key(kind)]
             return items unless items.nil?
           end
 
           items = items_if_not_deleted(@core.get_all_internal(kind))
-          @cache[all_cache_key(kind)] = items unless @cache.nil?
+          cache[all_cache_key(kind)] = items unless cache.nil?
           items
         end
 
         def upsert(kind, item)
           new_state = @core.upsert_internal(kind, item)
 
-          unless @cache.nil?
-            @cache[item_cache_key(kind, item[:key])] = [new_state]
-            @cache.delete(all_cache_key(kind))
+          cache = @cache
+          unless cache.nil?
+            cache[item_cache_key(kind, item[:key])] = [new_state]
+            cache.delete(all_cache_key(kind))
           end
         end
 
@@ -115,13 +117,14 @@ module LaunchDarkly
         def initialized?
           return true if @inited.value
 
-          if @cache.nil?
+          cache = @cache
+          if cache.nil?
             result = @core.initialized_internal?
           else
-            result = @cache[inited_cache_key]
+            result = cache[inited_cache_key]
             if result.nil?
               result = @core.initialized_internal?
-              @cache[inited_cache_key] = result
+              cache[inited_cache_key] = result
             end
           end
 
@@ -129,6 +132,23 @@ module LaunchDarkly
           result
         end
 
+        #
+        # Disable the in-memory cache. Releases the cache reference so subsequent operations
+        # bypass it and go directly to the underlying core. Safe to call multiple times.
+        #
+        # Called by the FDv2 store coordinator once the in-memory store has become the
+        # source of truth and the persistent-store cache is no longer useful. Internal --
+        # not part of the public API.
+        #
+        # @return [void]
+        #
+        def disable_cache
+          cache = @cache
+          return if cache.nil?
+          @cache = nil
+          cache.clear
+        end
+
         def stop
           @core.stop
         end