launchdarkly-server-sdk 8.18.3 → 8.19.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4226a694d1de20c401da7e78771104c435b2fdb0dc463869ec579247397bc5ef
-  data.tar.gz: 4eeba235b1ce96d33d5452ec6108bfc9fc2a10714a3bb253a2d5aa80f96ef380
+  metadata.gz: 298f46f5f43d9fa4ae2a0b464d7c08851e9fd8dd61aed07ca3cfb7cb18937135
+  data.tar.gz: 72365ba993ef0ff4b14d41bfdc96abe6a0aabb780262b206d1a82dcf55462d62
 SHA512:
-  metadata.gz: 9e5c17df985d102185e213b31736692df18da0e053cd5b94d41f2102714253018fefe841a0ef49f62aa1c3f4a497f70b9005bdc131d6bbc9445f6c0493a23832
-  data.tar.gz: 6a79cedd29e66574fa438372090f9c1c1b3abe4dea07b4e25409142a48b8ed1d1ad61c162ebacf7c9c6581cc0c558634f790d2b454fe7be246447a7c0cd10410
+  metadata.gz: 82681ba9cf9a951e673b38ae22ca9c2889efd382afce638144fbd7ec61be80ec863381b04c5a57c0881466e2736f7d12629ab9738ffd530b52312277a9ef0f40
+  data.tar.gz: be74527772fcfa14c543d27fc31980a1450d5c8cbc5e4d8ac0b3b1d7f204cfbf4ebf4f73e889e8f1200c88879fc49792e1a6404ad01d932a269c745834e49754

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

@@ -1,5 +1,6 @@
 require "ldclient-rb/impl/data_source"
 require "ldclient-rb/impl/repeating_task"
+require "ldclient-rb/impl/retry_state"
 require "ldclient-rb/impl/util"
 
 require "concurrent/atomics"
@@ -16,7 +17,8 @@ module LaunchDarkly
           @initialized = Concurrent::AtomicBoolean.new(false)
           @started = Concurrent::AtomicBoolean.new(false)
           @ready = Concurrent::Event.new
-          @task = Impl::RepeatingTask.new(@config.poll_interval, 0, -> { self.poll }, @config.logger, 'LD/PollingDataSource')
+          @retry_state = Impl::RetryState.for_polling(@config.poll_interval, @config.logger)
+          @task = Impl::RepeatingTask.new(-> { @retry_state.next_delay }, 0, -> { self.poll }, @config.logger, 'LD/PollingDataSource')
         end
 
         def initialized?
@@ -43,6 +45,7 @@ module LaunchDarkly
               update_sink_or_data_store.init(all_data)
               newly_initialized = @initialized.make_true
             end
+            @retry_state.record_success
             @config.data_source_update_sink&.update_status(LaunchDarkly::Interfaces::DataSource::Status::VALID, nil)
 
             if newly_initialized
@@ -50,7 +53,8 @@ module LaunchDarkly
               @ready.set
             end
           rescue JSON::ParserError => e
-            @config.logger.error { "[LDClient] JSON parsing failed for polling response." }
+            @retry_state.record_failure(:normal)
+            @config.logger.error { "[LDClient] JSON parsing failed for polling response - #{Util.retry_message(@retry_state.next_delay)}" }
             error_info = LaunchDarkly::Interfaces::DataSource::ErrorInfo.new(
               LaunchDarkly::Interfaces::DataSource::ErrorInfo::INVALID_DATA,
               0,
@@ -59,25 +63,16 @@ module LaunchDarkly
             )
             @config.data_source_update_sink&.update_status(LaunchDarkly::Interfaces::DataSource::Status::INTERRUPTED, error_info)
           rescue Impl::DataSource::UnexpectedResponseError => e
+            kind = Util.classify_http_status(e.status)
+            @retry_state.record_failure(kind)
             error_info = LaunchDarkly::Interfaces::DataSource::ErrorInfo.new(
               LaunchDarkly::Interfaces::DataSource::ErrorInfo::ERROR_RESPONSE, e.status, nil, Time.now)
-            message = Util.http_error_message(e.status, "polling request", "will retry")
-            @config.logger.error { "[LDClient] #{message}" }
-
-            if Util.http_error_recoverable?(e.status)
-              @config.data_source_update_sink&.update_status(
-                LaunchDarkly::Interfaces::DataSource::Status::INTERRUPTED,
-                error_info
-              )
-            else
-              # Publish the OFF status before releasing anyone waiting on the
-              # ready event, so a client that returns from start can rely on the
-              # data source status already reflecting the failure.
-              stop_with_error_info error_info
-              @ready.set  # if client was waiting on us, make it stop waiting - has no effect if already set
-            end
+            message = Util.http_error_retry_message(e.status, "polling request", @retry_state.next_delay)
+            @config.logger.public_send(Util.failure_log_level(kind)) { "[LDClient] #{message}" }
+            @config.data_source_update_sink&.update_status(LaunchDarkly::Interfaces::DataSource::Status::INTERRUPTED, error_info)
           rescue StandardError => e
-            Impl::Util.log_exception(@config.logger, "Exception while polling", e)
+            @retry_state.record_failure(:normal)
+            Impl::Util.log_exception(@config.logger, "Exception while polling - #{Util.retry_message(@retry_state.next_delay)}", e)
             @config.data_source_update_sink&.update_status(
               LaunchDarkly::Interfaces::DataSource::Status::INTERRUPTED,
               LaunchDarkly::Interfaces::DataSource::ErrorInfo.new(LaunchDarkly::Interfaces::DataSource::ErrorInfo::UNKNOWN, 0, e.to_s, Time.now)

data/lib/ldclient-rb/impl/data_source/stream.rb

@@ -1,5 +1,6 @@
 require "ldclient-rb/impl/data_source"
 require "ldclient-rb/impl/model/serialization"
+require "ldclient-rb/impl/retry_state"
 require "ldclient-rb/impl/util"
 require "ldclient-rb/in_memory_store"
 
@@ -31,6 +32,8 @@ module LaunchDarkly
           @started = Concurrent::AtomicBoolean.new(false)
           @stopped = Concurrent::AtomicBoolean.new(false)
           @ready = Concurrent::Event.new
+          @stop_event = Concurrent::Event.new
+          @retry_state = Impl::RetryState.for_streaming(@config.initial_reconnect_delay, @config.logger)
           @connection_attempt_start_time = 0
           @connection_attempt_started_monotonic = nil
         end
@@ -51,7 +54,8 @@ module LaunchDarkly
             connect_timeout: @config.connect_timeout,
             logger: @config.logger,
             socket_factory: @config.socket_factory,
-            reconnect_time: @config.initial_reconnect_delay,
+            # The SDK waits in its error handler before each reconnect, so the SSE client adds no delay.
+            reconnect_time: 0,
           }
           log_connection_started
 
@@ -59,39 +63,10 @@ module LaunchDarkly
           @es = SSE::Client.new(uri, **opts) do |conn|
             conn.on_connect { |response_headers| DataSource.record_environment_id(@data_source_update_sink, response_headers) }
             conn.on_event { |event| process_message(event) }
-            conn.on_error { |err|
-              log_connection_result(false)
-              case err
-              when SSE::Errors::HTTPStatusError
-                status = err.status
-                error_info = LaunchDarkly::Interfaces::DataSource::ErrorInfo.new(
-                  LaunchDarkly::Interfaces::DataSource::ErrorInfo::ERROR_RESPONSE, status, nil, Time.now)
-                message = Util.http_error_message(status, "streaming connection", "will retry")
-                @config.logger.error { "[LDClient] #{message}" }
-
-                if Util.http_error_recoverable?(status)
-                  @data_source_update_sink&.update_status(
-                    LaunchDarkly::Interfaces::DataSource::Status::INTERRUPTED,
-                    error_info
-                  )
-                else
-                  @ready.set  # if client was waiting on us, make it stop waiting - has no effect if already set
-                  stop_with_error_info error_info
-                end
-              when SSE::Errors::HTTPContentTypeError, SSE::Errors::HTTPProxyError, SSE::Errors::ReadTimeoutError
-                @data_source_update_sink&.update_status(
-                  LaunchDarkly::Interfaces::DataSource::Status::INTERRUPTED,
-                  LaunchDarkly::Interfaces::DataSource::ErrorInfo.new(LaunchDarkly::Interfaces::DataSource::ErrorInfo::NETWORK_ERROR, 0, err.to_s, Time.now)
-                )
-
-              else
-                @data_source_update_sink&.update_status(
-                  LaunchDarkly::Interfaces::DataSource::Status::INTERRUPTED,
-                  LaunchDarkly::Interfaces::DataSource::ErrorInfo.new(LaunchDarkly::Interfaces::DataSource::ErrorInfo::UNKNOWN, 0, err.to_s, Time.now)
-                )
-              end
-            }
+            conn.on_error { |err| handle_error(err) }
           end
+          # stop can run before @es is set, and then it has no client to close.
+          @es.close if @stopped.value
 
           @ready
         end
@@ -106,10 +81,73 @@ module LaunchDarkly
         # @param [LaunchDarkly::Interfaces::DataSource::ErrorInfo, nil] error_info
         #
         def stop_with_error_info(error_info = nil)
-          if @stopped.make_true
-            @es.close
-            @data_source_update_sink&.update_status(LaunchDarkly::Interfaces::DataSource::Status::OFF, error_info)
-            @config.logger.info { "[LDClient] Stream connection stopped" }
+          return unless @stopped.make_true
+
+          @stop_event.set
+          begin
+            @es&.close
+          rescue StandardError => e
+            Impl::Util.log_exception(@config.logger, "Error while closing stream connection", e)
+          end
+          @data_source_update_sink&.update_status(LaunchDarkly::Interfaces::DataSource::Status::OFF, error_info)
+          @config.logger.info { "[LDClient] Stream connection stopped" }
+        end
+
+        def handle_error(err)
+          status = 0
+          message = err.to_s
+          kind = :normal
+          level = :warn
+
+          case err
+          when SSE::Errors::HTTPStatusError
+            status = err.status
+            message = nil
+            kind = Util.classify_http_status(status)
+            level = Util.failure_log_level(kind)
+            error_kind = LaunchDarkly::Interfaces::DataSource::ErrorInfo::ERROR_RESPONSE
+            description = Util.http_error_description(status, "streaming connection")
+          when JSON::ParserError
+            level = :error
+            error_kind = LaunchDarkly::Interfaces::DataSource::ErrorInfo::INVALID_DATA
+            description = "Invalid data on streaming connection: #{err}"
+          when SSE::Errors::StreamClosedByServerError
+            error_kind = LaunchDarkly::Interfaces::DataSource::ErrorInfo::NETWORK_ERROR
+            description = "The server closed the streaming connection"
+          when SSE::Errors::HTTPContentTypeError, SSE::Errors::HTTPProxyError, SSE::Errors::ReadTimeoutError
+            error_kind = LaunchDarkly::Interfaces::DataSource::ErrorInfo::NETWORK_ERROR
+            description = "Error on streaming connection: #{err}"
+          else
+            error_kind = LaunchDarkly::Interfaces::DataSource::ErrorInfo::UNKNOWN
+            description = "Error on streaming connection: #{err}"
+          end
+
+          error_info = LaunchDarkly::Interfaces::DataSource::ErrorInfo.new(error_kind, status, message, Time.now)
+          handle_failure(kind, error_info, level, description)
+        end
+
+        #
+        # Records a failure, logs and reports it, and waits before the next attempt. The SSE client calls this on
+        # its worker thread before it reconnects, so the wait is the reconnect delay, and {#stop} ends it at once.
+        #
+        # @param kind [Symbol] `:normal` or `:unexpected`
+        # @param error_info [LaunchDarkly::Interfaces::DataSource::ErrorInfo]
+        # @param level [Symbol] `:error` or `:warn`
+        # @param description [String] what failed, for the log message
+        #
+        def handle_failure(kind, error_info, level, description)
+          return if @stopped.value
+
+          @retry_state.record_failure(kind)
+          delay = @retry_state.next_delay
+          begin
+            log_connection_result(false)
+            @config.logger.public_send(level) { "[LDClient] #{description} - #{Util.retry_message(delay)}" }
+            @data_source_update_sink&.update_status(LaunchDarkly::Interfaces::DataSource::Status::INTERRUPTED, error_info)
+          ensure
+            # The SSE client reconnects as soon as this returns, also when it returns by raising.
+            @stop_event.wait([delay, Util::TIMEOUT_MAX].min)
+            log_connection_started
           end
         end
 
@@ -131,6 +169,7 @@ module LaunchDarkly
         def process_message(message)
           log_connection_result(true)
           method = message.type
+          known_type = [PUT, PATCH, DELETE].include?(method)
           @config.logger.debug { "[LDClient] Stream received #{method} message: #{message.data}" }
 
           begin
@@ -164,16 +203,11 @@ module LaunchDarkly
               @config.logger.warn { "[LDClient] Unknown message received: #{method}" }
             end
 
+            # Only a data payload shows that the stream is healthy.
+            @retry_state.record_success if known_type
             @data_source_update_sink&.update_status(LaunchDarkly::Interfaces::DataSource::Status::VALID, nil)
-          rescue JSON::ParserError => e
+          rescue JSON::ParserError
             @config.logger.error { "[LDClient] JSON parsing failed for method #{method}. Ignoring event." }
-            error_info = LaunchDarkly::Interfaces::DataSource::ErrorInfo.new(
-              LaunchDarkly::Interfaces::DataSource::ErrorInfo::INVALID_DATA,
-              0,
-              e.to_s,
-              Time.now
-            )
-            @data_source_update_sink&.update_status(LaunchDarkly::Interfaces::DataSource::Status::INTERRUPTED, error_info)
 
             # Re-raise the exception so the SSE implementation can catch it and restart the stream.
             raise

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

@@ -138,6 +138,9 @@ module LaunchDarkly
           @mutex.synchronize do
             old_status = @current_status
 
+            # OFF is final: no status is reported after it.
+            return if old_status.state == LaunchDarkly::Interfaces::DataSource::Status::OFF
+
             if new_state == LaunchDarkly::Interfaces::DataSource::Status::INTERRUPTED && old_status.state == LaunchDarkly::Interfaces::DataSource::Status::INITIALIZING
               # See {LaunchDarkly::Interfaces::DataSource::UpdateSink#update_status} for more information
               new_state = LaunchDarkly::Interfaces::DataSource::Status::INITIALIZING

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

@@ -334,7 +334,8 @@ module LaunchDarkly
 
             @logger.warn { "[LDClient] #{error_info.message}" }
 
-          when SSE::Errors::HTTPContentTypeError, SSE::Errors::HTTPProxyError, SSE::Errors::ReadTimeoutError
+          when SSE::Errors::HTTPContentTypeError, SSE::Errors::HTTPProxyError, SSE::Errors::ReadTimeoutError,
+               SSE::Errors::StreamClosedByServerError
             @logger.warn { "[LDClient] Network error on stream connection: #{error}, will retry" }
 
             update = LaunchDarkly::Interfaces::DataSystem::Update.new(

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

@@ -5,8 +5,10 @@ require "concurrent/atomics"
 module LaunchDarkly
   module Impl
     #
-    # Runs a task again and again on a worker thread, with a fixed interval
-    # between runs.
+    # Runs a task again and again on a worker thread.
+    #
+    # The interval is read after each run, and the wait starts when the run
+    # returns.
     #
     # The worker waits on an event instead of calling `sleep`, so `stop` can
     # wake it at once even if `stop` runs before the worker starts waiting.
@@ -14,10 +16,15 @@ module LaunchDarkly
     # @private
     #
     class RepeatingTask
+      # The wait, in seconds, when a callable interval raises or returns a value that is not a usable
+      # number. It must not be 0: a broken callable would then run the task back to back, which for
+      # polling is a tight loop of HTTP requests.
+      FALLBACK_INTERVAL = 1
+
       attr_reader :name
 
       #
-      # @param interval [Numeric] seconds between the start of one run and the start of the next
+      # @param interval [Numeric, #call] seconds between runs, or an object that returns them
       # @param start_delay [Numeric, nil] seconds to wait before the first run
       # @param task [Proc] the code to run
       # @param logger [Logger]
@@ -39,22 +46,32 @@ module LaunchDarkly
           @stop_event.wait(@start_delay) unless @start_delay.nil? || @start_delay == 0
 
           until @stopped.value do
-            started_at = Impl::Util.monotonic_seconds
             begin
               @task.call
             rescue => e
               Impl::Util.log_exception(@logger, "Uncaught exception from repeating task", e)
             end
-            # The run must be measured on the monotonic clock: a wall-clock step would
-            # make this wait negative (immediate re-run) or stretch it by the step size.
-            delta = @interval - (Impl::Util.monotonic_seconds - started_at)
-            @stop_event.wait(delta) if delta > 0
+            delay = next_delay
+            @stop_event.wait([delay, Util::TIMEOUT_MAX].min) if delay > 0
           end
         end
 
         @worker.name = @name
       end
 
+      private def next_delay
+        return @interval if @interval.is_a?(Numeric)
+
+        delay = @interval.call
+        return delay if delay.is_a?(Numeric) && delay >= 0
+
+        @logger.error { "[LDClient] Repeating task #{@name} got an invalid interval #{delay.inspect}; waiting #{FALLBACK_INTERVAL}s" }
+        FALLBACK_INTERVAL
+      rescue => e
+        Impl::Util.log_exception(@logger, "Exception while reading the interval of repeating task #{@name}", e)
+        FALLBACK_INTERVAL
+      end
+
       #
       # Stops the worker thread and waits for it to finish.
       #

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

@@ -0,0 +1,240 @@
+require "ldclient-rb/config"
+require "ldclient-rb/impl/util"
+
+module LaunchDarkly
+  module Impl
+    #
+    # Computes how long to wait before a failed operation is tried again.
+    #
+    # Each failure is `:normal` or `:unexpected`. After a normal failure, the wait starts at the normal
+    # initial delay and doubles with each failure, up to the normal ceiling. An unexpected failure moves
+    # the state to the extended regime: the wait starts at the extended initial delay and doubles up to
+    # the extended ceiling. The extended bounds stay in place until the reset policy is satisfied, so a
+    # normal failure that follows cannot lower them. When the policy is satisfied, the state returns to
+    # the normal regime and the delay sequence starts over.
+    #
+    # A random jitter of up to half of each delay is subtracted, so that many callers do not all try
+    # again at the same moment. The wait never falls below the operating cadence.
+    #
+    # After each outcome, call {#record_failure} or {#record_success}, then read {#next_delay} for the
+    # wait before the next operation. An instance is not thread-safe.
+    #
+    # @private
+    #
+    class RetryState
+      # The longest normal delay for streaming, in seconds.
+      NORMAL_STREAMING_CEILING_DELAY = 30
+
+      # The delay bounds of the extended regime, in seconds.
+      EXTENDED_INITIAL_DELAY = 5 * 60
+      EXTENDED_CEILING_DELAY = 60 * 60
+
+      # How long a stream must operate without a failure before its retry state resets, in seconds.
+      STREAMING_RESET_INTERVAL = 60
+
+      # How many polls in a row must succeed before polling's retry state resets.
+      POLLING_RESET_SUCCESSES = 2
+
+      MONOTONIC_CLOCK = -> { Impl::Util.monotonic_seconds }
+      private_constant :MONOTONIC_CLOCK
+
+      #
+      # Builds the retry state for a streaming data source.
+      #
+      # A healthy stream never waits, so the operating cadence is zero. A delay that is not a
+      # positive, finite number is replaced by the default. A delay longer than a ceiling raises that
+      # ceiling.
+      #
+      # @param initial_reconnect_delay [Numeric] seconds
+      # @param logger [Logger]
+      # @param clock [#call] returns monotonic seconds
+      # @param random [#rand] returns a Float in [0, 1)
+      # @return [RetryState]
+      #
+      def self.for_streaming(initial_reconnect_delay, logger, clock: MONOTONIC_CLOCK, random: Random.new)
+        delay = usable_delay(initial_reconnect_delay, Config.default_initial_reconnect_delay, "initial_reconnect_delay", logger)
+        new(
+          normal_initial_delay: delay,
+          normal_ceiling_delay: NORMAL_STREAMING_CEILING_DELAY,
+          extended_initial_delay: [EXTENDED_INITIAL_DELAY, delay].max,
+          extended_ceiling_delay: EXTENDED_CEILING_DELAY,
+          reset_policy: AfterHealthyFor.new(STREAMING_RESET_INTERVAL, clock),
+          operating_cadence: 0,
+          random: random
+        )
+      end
+
+      #
+      # Builds the retry state for a polling data source.
+      #
+      # The poll interval is both the operating cadence and the normal ceiling, so a normal failure
+      # waits the interval. An interval that is not a positive, finite number is replaced by the
+      # default. No wait is shorter than the interval, so the interval wins over the extended ceiling.
+      #
+      # @param poll_interval [Numeric] seconds
+      # @param logger [Logger]
+      # @param random [#rand] returns a Float in [0, 1)
+      # @return [RetryState]
+      #
+      def self.for_polling(poll_interval, logger, random: Random.new)
+        interval = usable_delay(poll_interval, Config.default_poll_interval, "poll_interval", logger)
+        new(
+          normal_initial_delay: interval,
+          normal_ceiling_delay: interval,
+          extended_initial_delay: [EXTENDED_INITIAL_DELAY, interval].max,
+          extended_ceiling_delay: EXTENDED_CEILING_DELAY,
+          reset_policy: AfterConsecutiveSuccesses.new(POLLING_RESET_SUCCESSES),
+          operating_cadence: interval,
+          random: random
+        )
+      end
+
+      private_class_method def self.usable_delay(value, default, name, logger)
+        return value if value.is_a?(Numeric) && value.real? && value > 0 && value.finite?
+
+        logger.warn { "[LDClient] #{name} must be a positive, finite number of seconds; using the default of #{default}s" }
+        default
+      end
+
+      #
+      # @param normal_initial_delay [Numeric] the first normal delay, in seconds
+      # @param normal_ceiling_delay [Numeric] the longest normal delay, in seconds
+      # @param extended_initial_delay [Numeric] the first extended delay, in seconds
+      # @param extended_ceiling_delay [Numeric] the longest extended delay, in seconds
+      # @param reset_policy [AfterHealthyFor, AfterConsecutiveSuccesses] decides when the state resets
+      # @param operating_cadence [Numeric] the wait between healthy operations, in seconds; no wait is
+      #   shorter than this
+      # @param random [#rand] returns a Float in [0, 1)
+      #
+      def initialize(normal_initial_delay:, normal_ceiling_delay:, extended_initial_delay:, extended_ceiling_delay:,
+        reset_policy:, operating_cadence: 0, random: Random.new)
+        @normal_initial_delay = normal_initial_delay
+        @normal_ceiling_delay = normal_ceiling_delay
+        @extended_initial_delay = extended_initial_delay
+        @extended_ceiling_delay = extended_ceiling_delay
+        @reset_policy = reset_policy
+        @operating_cadence = operating_cadence
+        @random = random
+
+        @attempts = 0
+        @extended = false
+        @min_delay = @normal_initial_delay
+        @max_delay = [@normal_ceiling_delay, @normal_initial_delay].max
+        @next_delay = @operating_cadence
+      end
+
+      #
+      # @return [Numeric] the wait before the next operation, in seconds, as the last recorded
+      #   outcome decided it
+      #
+      attr_reader :next_delay
+
+      #
+      # Records a failed attempt and decides the wait before the next one.
+      #
+      # @param kind [Symbol] `:normal` or `:unexpected`
+      # @return [void]
+      #
+      def record_failure(kind)
+        # A caller can record nothing while it is healthy, so a time-based reset can only be noticed here.
+        reset_if_due
+        @reset_policy.note_failure
+
+        if kind == :unexpected && !@extended
+          # Only the move to the extended regime starts the sequence over. A later unexpected failure
+          # keeps counting up.
+          @extended = true
+          @min_delay = @extended_initial_delay
+          @max_delay = [@extended_ceiling_delay, @min_delay].max
+          @attempts = 1
+        else
+          @attempts += 1
+        end
+
+        delay = [@min_delay * (2**(@attempts - 1)), @max_delay].min
+        jitter = @random.rand * delay / 2
+        @next_delay = [delay - jitter, @operating_cadence].max
+      end
+
+      #
+      # Records a successful operation, and resets the retry state if the reset policy is satisfied.
+      #
+      # The next wait returns to the operating cadence even when the state has not reset, because a
+      # backoff delay applies to a retry and not to every operation.
+      #
+      # @return [void]
+      #
+      def record_success
+        @reset_policy.note_healthy
+        reset_if_due
+        @next_delay = @operating_cadence
+      end
+
+      private def reset_if_due
+        return unless @reset_policy.satisfied?
+
+        @attempts = 0
+        @extended = false
+        @min_delay = @normal_initial_delay
+        @max_delay = [@normal_ceiling_delay, @normal_initial_delay].max
+      end
+
+      #
+      # Resets once the component has operated without a failure for a number of seconds.
+      #
+      # @private
+      #
+      class AfterHealthyFor
+        #
+        # @param seconds [Numeric]
+        # @param clock [#call] returns monotonic seconds
+        #
+        def initialize(seconds, clock)
+          @healthy_seconds = seconds
+          @clock = clock
+          @healthy_since = nil
+        end
+
+        # A later call during the same healthy stretch does not move its start.
+        def note_healthy
+          @healthy_since = @clock.call if @healthy_since.nil?
+        end
+
+        def note_failure
+          @healthy_since = nil
+        end
+
+        def satisfied?
+          !@healthy_since.nil? && @clock.call - @healthy_since >= @healthy_seconds
+        end
+      end
+
+      #
+      # Resets once a number of operations in a row have succeeded.
+      #
+      # @private
+      #
+      class AfterConsecutiveSuccesses
+        #
+        # @param count [Integer]
+        #
+        def initialize(count)
+          @count = count
+          @successes = 0
+        end
+
+        def note_healthy
+          @successes += 1
+        end
+
+        def note_failure
+          @successes = 0
+        end
+
+        def satisfied?
+          @successes >= @count
+        end
+      end
+    end
+  end
+end

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

@@ -4,6 +4,10 @@ require "http"
 module LaunchDarkly
   module Impl
     module Util
+      # The longest wait to pass to `Concurrent::Event#wait`, in seconds. A wait above about 1e19 seconds
+      # raises `RangeError`. About 31 years is the same in practice as honoring a longer wait.
+      TIMEOUT_MAX = 1_000_000_000
+
       def self.bool?(aObject)
          [true,false].include? aObject
       end
@@ -162,19 +166,72 @@ module LaunchDarkly
         logger.debug { "[LDClient] Exception trace: #{exc.backtrace}" }
       end
 
-      def self.http_error_recoverable?(status)
-        if status >= 400 && status < 500
-          status == 400 || status == 408 || status == 429
+      # The 4xx statuses that are still normal failures. Every other 4xx is unexpected.
+      NORMAL_4XX_STATUSES = [400, 408, 429].freeze
+      private_constant :NORMAL_4XX_STATUSES
+
+      #
+      # Classifies an HTTP error status.
+      #
+      # `400`, `408`, `429` and every status outside the 4xx range are normal. Every other `4xx`,
+      # including `401` and `403`, is unexpected.
+      #
+      # @param status [Integer]
+      # @return [Symbol] `:normal` or `:unexpected`
+      #
+      def self.classify_http_status(status)
+        if status >= 400 && status < 500 && !NORMAL_4XX_STATUSES.include?(status)
+          :unexpected
         else
-          true
+          :normal
         end
       end
 
+      def self.http_error_recoverable?(status)
+        classify_http_status(status) == :normal
+      end
+
       def self.http_error_message(status, context, recoverable_message)
         desc = (status == 401 || status == 403) ? " (invalid SDK key)" : ""
         message = http_error_recoverable?(status) ? recoverable_message : "giving up permanently"
         "HTTP error #{status}#{desc} for #{context} - #{message}"
       end
+
+      #
+      # @param status [Integer]
+      # @param context [String] what failed, such as "polling request"
+      # @return [String]
+      #
+      def self.http_error_description(status, context)
+        desc = (status == 401 || status == 403) ? " (invalid SDK key)" : ""
+        "HTTP error #{status}#{desc} for #{context}"
+      end
+
+      #
+      # @param status [Integer]
+      # @param context [String] what failed, such as "polling request"
+      # @param delay [Numeric] seconds until the next attempt
+      # @return [String]
+      #
+      def self.http_error_retry_message(status, context, delay)
+        "#{http_error_description(status, context)} - #{retry_message(delay)}"
+      end
+
+      #
+      # @param kind [Symbol] `:normal` or `:unexpected`
+      # @return [Symbol] the log level for a failure of this kind
+      #
+      def self.failure_log_level(kind)
+        kind == :unexpected ? :error : :warn
+      end
+
+      #
+      # @param delay [Numeric] seconds until the next attempt
+      # @return [String]
+      #
+      def self.retry_message(delay)
+        format("will retry in %.1fs", delay)
+      end
     end
   end
 end

data/lib/ldclient-rb/interfaces/data_source.rb

@@ -148,6 +148,8 @@ module LaunchDarkly
         # {Status::INITIALIZING} because {Status::INTERRUPTED} is only meaningful
         # after a successful startup.
         #
+        # After a {Status::OFF} status, the SDK ignores every later update.
+        #
         # @param new_state [Symbol]
         # @param new_error [ErrorInfo, nil]
         #
@@ -161,9 +163,10 @@ module LaunchDarkly
         #
         # The initial state of the data source when the SDK is being initialized.
         #
-        # If it encounters an error that requires it to retry initialization, the state will remain at
-        # {INITIALIZING} until it either succeeds and becomes {VALID}, or permanently fails and
-        # becomes {OFF}.
+        # If it encounters an error while it initializes, it retries, and the state remains at
+        # {INITIALIZING} until it succeeds and becomes {VALID}. This is also true for an error that needs
+        # to be fixed, such as a rejected SDK key. In the FDv2 data system, it can instead become {OFF}
+        # after an error it does not retry.
         #
 
         INITIALIZING = :initializing
@@ -183,16 +186,19 @@ module LaunchDarkly
         #
         # In streaming mode, this means that the stream connection failed, or had to be dropped due to some
         # other error, and will be retried after a backoff delay. In polling mode, it means that the last poll
-        # request failed, and a new poll request will be made after the configured polling interval.
+        # request failed, and a new poll request will be made after the polling interval, or after a longer
+        # backoff delay for unexpected error types.
         #
         INTERRUPTED = :interrupted
 
         #
         # Indicates that the data source has been permanently shut down.
         #
-        # This could be because it encountered an unrecoverable error (for instance, the LaunchDarkly service
-        # rejected the SDK key; an invalid SDK key will never become valid), or because the SDK client was
-        # explicitly shut down.
+        # This could be because the SDK client was explicitly shut down. In the FDv2 data system, it can also
+        # mean the data source stopped after an error it does not retry.
+        #
+        # Unless the SDK is configured with {LaunchDarkly::Config#data_system_config}, no other state follows
+        # this one.
         #
         OFF = :off
 

data/lib/ldclient-rb/ldclient.rb

@@ -303,8 +303,9 @@ module LaunchDarkly
     # If this returns false, it means that the client did not succeed in connecting to
     # LaunchDarkly within the time limit that you specified in the constructor. It could
     # still succeed in connecting at a later time (on another thread), or it could have
-    # given up permanently (for instance, if your SDK key is invalid). In the meantime,
-    # any call to {#variation} or {#variation_detail} will behave as follows:
+    # received an error that needs to be fixed (for instance, if your SDK key is
+    # invalid). In the meantime, any call to {#variation} or {#variation_detail} will
+    # behave as follows:
     #
     # 1. It will check whether the feature store already contains data (that is, you
     # are using a database-backed store and it was populated by a previous run of this

data/lib/ldclient-rb/version.rb

@@ -1,3 +1,3 @@
 module LaunchDarkly
-  VERSION = "8.18.3" # x-release-please-version
+  VERSION = "8.19.0" # x-release-please-version
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: launchdarkly-server-sdk
 version: !ruby/object:Gem::Version
-  version: 8.18.3
+  version: 8.19.0
 platform: ruby
 authors:
 - LaunchDarkly
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-09 00:00:00.000000000 Z
+date: 2026-10-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: aws-sdk-dynamodb
@@ -252,14 +252,14 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 2.6.0
+        version: 3.0.1
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 2.6.0
+        version: 3.0.1
 - !ruby/object:Gem::Dependency
   name: observer
   requirement: !ruby/object:Gem::Requirement
@@ -437,6 +437,7 @@ files:
 - lib/ldclient-rb/impl/model/serialization.rb
 - lib/ldclient-rb/impl/non_blocking_thread_pool.rb
 - lib/ldclient-rb/impl/repeating_task.rb
+- lib/ldclient-rb/impl/retry_state.rb
 - lib/ldclient-rb/impl/sampler.rb
 - lib/ldclient-rb/impl/simple_lru_cache.rb
 - lib/ldclient-rb/impl/store_client_wrapper.rb