analytics-ruby 2.5.0 → 2.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cec8be05188f102d0622c0c82771728e855506fb1d1872b6c83a6668515ee667
-  data.tar.gz: 8ff1887eac5cdbf44ce702b6cbcf40fdbae60d52e8a4c6adade4637941e0ee04
+  metadata.gz: 93b810e0ef6d4ef896010dfc80c9997308f0761ac2f79345d96fa434f7dd66a3
+  data.tar.gz: e69ffd005078968e7137d220d8f9e51249a5452ae5311bc37757b21ea9cf82c4
 SHA512:
-  metadata.gz: 94ea84292a05e8a922f82b59d2eed172202839918a59aa978c2fb00e083fb1620f81b86105b49c20607e318bcb8fe7d7a377e96df91c941a182cf23eddde1514
-  data.tar.gz: add48055b0e80a97bba09e2b3278f0fee2b25b074591150efc079ed244fa8ae5d8c0829b7b22c465b93ea214db4dd4e5d029d2c78053c3a4cebd74c3db88fd8c
+  metadata.gz: 4619b6a5a332fd6da925f508c8e8ca58534236d597994ab0945840712d3761729a4c9dcf0a9aba2191e8f84f5191b853db9f1f854f047b00c46927ca98257c36
+  data.tar.gz: 9a6a6ca7a0c8c386dc9646c8521fb8000b183bd56d14d8da0a11e58117bd6beabd59048e8495f96b7acaab4624ad481c173dc3b781ca6dbbdcb24bd05d725a00

data/lib/segment/analytics/backoff_policy.rb

@@ -26,25 +26,17 @@ module Segment
       # @return [Numeric] the next backoff interval, in milliseconds.
       def next_interval
         interval = @min_timeout_ms * (@multiplier**@attempts)
-        interval = add_jitter(interval, @randomization_factor)
-
         @attempts += 1
 
-        [interval, @max_timeout_ms].min
+        # Clamp first, then jitter. Jittering before the clamp meant every attempt
+        # at the ceiling returned exactly max_timeout_ms, so a fleet that backed off
+        # together stayed in lockstep. Jitter only subtracts, so the ceiling holds.
+        capped = [interval, @max_timeout_ms].min
+        capped - (rand * capped * @randomization_factor)
       end
 
-      private
-
-      def add_jitter(base, randomization_factor)
-        random_number = rand
-        max_deviation = base * randomization_factor
-        deviation = random_number * max_deviation
-
-        if random_number < 0.5
-          base - deviation
-        else
-          base + deviation
-        end
+      def reset!
+        @attempts = 0
       end
     end
   end

data/lib/segment/analytics/client.rb

@@ -32,7 +32,11 @@ module Segment
 
         check_write_key!
 
-        at_exit { @worker_thread && @worker_thread[:should_exit] = true }
+        # The worker checks this between sleep slices, so a Retry-After or backoff
+        # wait is abandoned within a second rather than holding shutdown for up to
+        # rate_limit_retry_after_cap seconds. Assigning to a dead thread is safe;
+        # Thread#wakeup is not, and raising here would force a non-zero exit status.
+        at_exit { @worker_thread[:should_exit] = true if @worker_thread }
       end
 
       # Synchronously waits until the worker has flushed the queue.

data/lib/segment/analytics/defaults.rb

@@ -12,6 +12,20 @@ module Segment
                     'Content-Type' => 'application/json',
                     'User-Agent' => "analytics-ruby/#{Analytics::VERSION}" }
         RETRIES = 10
+        MAX_TOTAL_BACKOFF_DURATION = 43_200 # 12 hours in seconds
+
+        # Rate-limited attempts are deliberately uncounted, so this duration is the
+        # only thing bounding them. It is deliberately several times
+        # RATE_LIMIT_RETRY_AFTER_CAP: when the two are equal a single maximal
+        # Retry-After consumes the whole budget, leaving one attempt and no retry,
+        # and the cap can never be the smaller of the two so it never binds at all.
+        MAX_RATE_LIMIT_DURATION = 1800 # seconds
+
+        # A guard against an absurd header, not a second budget. Waiting less than
+        # the server asked for does not make the next attempt more likely to
+        # succeed, it just sends more requests at something already rate-limiting
+        # us; how long we keep trying is MAX_RATE_LIMIT_DURATION's job.
+        RATE_LIMIT_RETRY_AFTER_CAP = 300 # seconds
       end
 
       module Queue
@@ -28,9 +42,9 @@ module Segment
       end
 
       module BackoffPolicy
-        MIN_TIMEOUT_MS = 100
-        MAX_TIMEOUT_MS = 10000
-        MULTIPLIER = 1.5
+        MIN_TIMEOUT_MS = 500
+        MAX_TIMEOUT_MS = 60_000
+        MULTIPLIER = 2
         RANDOMIZATION_FACTOR = 0.5
       end
     end

data/lib/segment/analytics/response.rb

@@ -12,6 +12,10 @@ module Segment
         @status = status
         @error  = error
       end
+
+      def success?
+        status >= 200 && status < 300
+      end
     end
   end
 end

data/lib/segment/analytics/retry_budget.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module Segment
+  class Analytics
+    # Tracks the two independent budgets one send may spend.
+    #
+    # A retryable status carrying Retry-After spends the rate-limit budget, which
+    # is bounded by wall clock only. Anything else retryable spends the counted
+    # backoff budget, bounded by both a retry count and wall clock. Keeping them
+    # separate is what stops a rate-limited server from exhausting the retries
+    # available to genuine failures.
+    #
+    # The caller performs the wait, so both methods return the delay in seconds,
+    # or nil when the budget is spent and the batch should be abandoned.
+    class RetryBudget
+      attr_reader :retry_count
+
+      # Keyword arguments would be cleaner but need Ruby 2.1; the gemspec still
+      # declares >= 2.0, which is also what rubocop is configured to parse.
+      def initialize(options = {})
+        @retries_remaining = options[:retries]
+        @backoff_policy = options[:backoff_policy]
+        @max_total_backoff_duration = options[:max_total_backoff_duration]
+        @max_rate_limit_duration = options[:max_rate_limit_duration]
+        @rate_limit_retry_after_cap = options[:rate_limit_retry_after_cap]
+        @logger = options[:logger]
+        @retry_count = 0
+        @backoff_start_time = nil
+        @rate_limit_start_time = nil
+      end
+
+      def next_backoff_delay
+        # Checked before the decrement: decrementing first spent one retry on the
+        # exhaustion test itself, so a configured N only ever performed N-1, and
+        # retries: 1 and retries: 0 were indistinguishable.
+        return spent('Retries exhausted for batch') if @retries_remaining <= 0
+
+        @retries_remaining -= 1
+
+        # One reading for the budget test and the fit check below, as on the
+        # rate-limit path.
+        now = monotonic_now
+        @backoff_start_time ||= now
+
+        remaining = @max_total_backoff_duration - (now - @backoff_start_time)
+        return spent('Max total backoff duration exceeded for batch') if remaining <= 0
+
+        # A backoff longer than what is left of the budget is a wait whose attempt
+        # can never run, so there is nothing to schedule.
+        delay = @backoff_policy.next_interval.to_f / 1000
+        return spent('Backoff interval does not fit the remaining budget') if delay > remaining
+
+        @logger.debug("Retrying request, #{@retries_remaining} retries left. Waiting #{delay}s")
+        delay
+      end
+
+      def next_rate_limit_delay(retry_after, status_code)
+        # One reading serves the episode start, the budget test and the delay. A
+        # second reading lets the budget expire between them, which yields a negative
+        # remaining and a negative delay — and Kernel#sleep raises ArgumentError on
+        # one rather than returning immediately. It also leaves remaining a hair under
+        # the budget on an episode's first response, which is enough to lose an exact
+        # comparison against the cap.
+        now = monotonic_now
+        @rate_limit_start_time ||= now
+
+        remaining = @max_rate_limit_duration - (now - @rate_limit_start_time)
+        return spent('Max rate limit duration exceeded for batch') if remaining <= 0
+
+        # Capped, then required to fit. Shortening the wait to fit would send the
+        # next request inside the window the server asked us to wait out — one it
+        # has already said it will not serve — and the budget is spent by then, so
+        # it would be the last attempt either way. Giving up loses the same batch
+        # and sends one request fewer at something already rate-limiting us.
+        delay = [retry_after, @rate_limit_retry_after_cap].min
+        return spent('Retry-After does not fit the remaining rate limit budget') if delay > remaining
+
+        @logger.debug("Retry-After: #{delay}s on #{status_code}. Retrying after delay.")
+        delay
+      end
+
+      def record_retry
+        @retry_count += 1
+      end
+
+      private
+
+      def elapsed?(start_time, limit)
+        (monotonic_now - start_time) >= limit
+      end
+
+      # Wall-clock time can jump; these budgets must not expire or stretch with it.
+      def monotonic_now
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+
+      def spent(message)
+        @logger.error(message)
+        nil
+      end
+    end
+  end
+end

data/lib/segment/analytics/transport.rb

@@ -5,9 +5,11 @@ require 'segment/analytics/utils'
 require 'segment/analytics/response'
 require 'segment/analytics/logging'
 require 'segment/analytics/backoff_policy'
+require 'segment/analytics/retry_budget'
 require 'net/http'
 require 'net/https'
 require 'json'
+require 'time'
 
 module Segment
   class Analytics
@@ -16,22 +18,18 @@ module Segment
       include Segment::Analytics::Utils
       include Segment::Analytics::Logging
 
+      RETRYABLE_4XX     = [408, 410, 429, 460].freeze
+      NON_RETRYABLE_5XX = [501, 505, 511].freeze
+
       def initialize(options = {})
         options[:host] ||= HOST
         options[:port] ||= PORT
-        options[:ssl] ||= SSL
+        options[:ssl]  ||= SSL
         @headers = options[:headers] || HEADERS
-        @path = options[:path] || PATH
-        @retries = options[:retries] || RETRIES
-        @backoff_policy =
-          options[:backoff_policy] || Segment::Analytics::BackoffPolicy.new
+        @path    = options[:path]    || PATH
 
-        http = Net::HTTP.new(options[:host], options[:port])
-        http.use_ssl = options[:ssl]
-        http.read_timeout = 8
-        http.open_timeout = 4
-
-        @http = http
+        configure_retries(options)
+        @http = build_http(options)
       end
 
       # Sends a batch of messages to the API
@@ -40,23 +38,32 @@ module Segment
       def send(write_key, batch)
         logger.debug("Sending request for #{batch.length} items")
 
-        last_response, exception = retry_with_backoff(@retries) do
-          status_code, body = send_request(write_key, batch)
-          error = JSON.parse(body)['error']
-          should_retry = should_retry_request?(status_code, body)
-          logger.debug("Response status code: #{status_code}")
-          logger.debug("Response error: #{error}") if error
+        @backoff_policy.reset! if @backoff_policy.respond_to?(:reset!)
+        budget = new_retry_budget
 
-          [Response.new(status_code, error), should_retry]
-        end
+        loop do
+          begin
+            status_code, body, headers = send_request(write_key, batch, budget.retry_count)
+          rescue StandardError => e
+            # Connection reset, DNS failure, read timeout and friends. Retried on
+            # the counted backoff budget, like a retryable status code.
+            logger.error("Network error: #{e.message}")
+            return Response.new(-1, e.to_s) unless wait_to_retry(budget.next_backoff_delay, budget)
 
-        if exception
-          logger.error(exception.message)
-          exception.backtrace.each { |line| logger.error(line) }
-          Response.new(-1, exception.to_s)
-        else
-          last_response
+            next
+          end
+
+          error = parse_error(body)
+          final = final_response(status_code, body, error)
+          return final if final
+
+          delay = retry_delay(status_code, headers, budget)
+          return Response.new(status_code, error) unless wait_to_retry(delay, budget)
         end
+      rescue StandardError => e
+        logger.error(e.message)
+        e.backtrace.each { |line| logger.error(line) }
+        Response.new(-1, e.to_s)
       end
 
       # Closes a persistent connection if it exists
@@ -66,65 +73,174 @@ module Segment
 
       private
 
-      def should_retry_request?(status_code, body)
-        if status_code >= 500
-          true # Server error
-        elsif status_code == 429
-          true # Rate limited
-        elsif status_code >= 400
-          logger.error(body)
-          false # Client error. Do not retry, but log
+      # A Response once the batch is settled, or nil while it is still retryable.
+      def final_response(status_code, body, error)
+        logger.debug("Response status code: #{status_code}")
+        logger.debug("Response error: #{error}") if error
+
+        return Response.new(status_code, error) if success_status?(status_code)
+        return nil if retryable_status?(status_code)
+
+        if status_code >= 300 && status_code < 400
+          # Logging the body here would be useless: a redirect has none.
+          logger.error("Unexpected redirect (#{status_code}); batch not uploaded. " \
+                       'Check whether the configured host points at a proxy or redirector.')
         else
-          false
+          logger.error(body)
         end
+        Response.new(status_code, error)
       end
 
-      # Takes a block that returns [result, should_retry].
-      #
-      # Retries upto `retries_remaining` times, if `should_retry` is false or
-      # an exception is raised. `@backoff_policy` is used to determine the
-      # duration to sleep between attempts
+      # A Retry-After spends the rate-limit budget; anything else retryable
+      # spends the counted backoff budget.
+      def retry_delay(status_code, headers, budget)
+        retry_after = parse_retry_after(headers['retry-after'])
+        return budget.next_backoff_delay unless retry_after
+
+        budget.next_rate_limit_delay(retry_after, status_code)
+      end
+
+      def configure_retries(options)
+        @retries = options[:retries] || RETRIES
+        @backoff_policy =
+          options[:backoff_policy] || Segment::Analytics::BackoffPolicy.new
+
+        # One policy instance serves every batch, so it has to be reset between
+        # them or attempt counts accumulate and each batch starts where the last
+        # one left off. reset! is not part of the older documented contract, which
+        # was next_interval alone, so a policy predating it still works — but it
+        # keeps that accumulation, and silently. Say so rather than letting an
+        # integrator find it as "retries get slower the longer we run".
+        unless @backoff_policy.respond_to?(:reset!)
+          logger.warn(
+            'backoff_policy does not implement reset!; attempt counts will ' \
+            'accumulate across batches. Add a reset! method that clears them.'
+          )
+        end
+        @max_total_backoff_duration = options[:max_total_backoff_duration] ||
+                                      MAX_TOTAL_BACKOFF_DURATION
+        @max_rate_limit_duration    = options[:max_rate_limit_duration] ||
+                                      MAX_RATE_LIMIT_DURATION
+        @rate_limit_retry_after_cap = options[:rate_limit_retry_after_cap] ||
+                                      RATE_LIMIT_RETRY_AFTER_CAP
+      end
+
+      def build_http(options)
+        http = Net::HTTP.new(options[:host], options[:port])
+        http.use_ssl = options[:ssl]
+        http.read_timeout = 8
+        http.open_timeout = 4
+        http
+      end
+
+      # How long a sliced retry wait sleeps before re-checking for shutdown.
+      SHUTDOWN_CHECK_INTERVAL = 1
+
+      def new_retry_budget
+        RetryBudget.new(
+          :retries => @retries,
+          :backoff_policy => @backoff_policy,
+          :max_total_backoff_duration => @max_total_backoff_duration,
+          :max_rate_limit_duration => @max_rate_limit_duration,
+          :rate_limit_retry_after_cap => @rate_limit_retry_after_cap,
+          :logger => logger
+        )
+      end
+
+      # nil delay means the budget is spent. Sleeping here rather than inside
+      # RetryBudget keeps the wait on Transport, where callers stub it.
+      def wait_to_retry(delay, budget)
+        return false if delay.nil?
+        return false unless interruptible_sleep(delay)
+
+        budget.record_retry
+        true
+      end
+
+      # Sleeps in slices so shutdown is noticed within SHUTDOWN_CHECK_INTERVAL
+      # rather than after the whole delay, which can be rate_limit_retry_after_cap
+      # seconds. Returns false if shutdown was requested.
       #
-      # Returns [last_result, raised_exception]
-      def retry_with_backoff(retries_remaining, &block)
-        result, caught_exception = nil
-        should_retry = false
+      # Thread#wakeup is deliberately not used for this: it only cuts short a sleep
+      # already in progress, so a wakeup arriving while the worker is mid-request is
+      # lost and the next sleep still runs in full.
+      def interruptible_sleep(seconds)
+        remaining = seconds
+        while remaining > 0
+          return false if Thread.current[:should_exit]
 
-        begin
-          result, should_retry = yield
-          return [result, nil] unless should_retry
-        rescue StandardError => e
-          should_retry = true
-          caught_exception = e
+          slice = [remaining, SHUTDOWN_CHECK_INTERVAL].min
+          sleep(slice)
+          remaining -= slice
         end
+        !Thread.current[:should_exit]
+      end
 
-        if should_retry && (retries_remaining > 1)
-          logger.debug("Retrying request, #{retries_remaining} retries left")
-          sleep(@backoff_policy.next_interval.to_f / 1000)
-          retry_with_backoff(retries_remaining - 1, &block)
+      def parse_error(body)
+        JSON.parse(body)['error']
+      rescue StandardError
+        nil
+      end
+
+      # Only 2xx. Net::HTTP does not follow redirects, so a 3xx means nothing was
+      # uploaded; calling it success would drop the batch silently.
+      def success_status?(code)
+        code >= 200 && code < 300
+      end
+
+      def retryable_status?(code)
+        if code >= 500 && code < 600
+          !NON_RETRYABLE_5XX.include?(code)
         else
-          [result, caught_exception]
+          RETRYABLE_4XX.include?(code)
+        end
+      end
+
+      def parse_retry_after(value)
+        return nil if value.nil?
+
+        str = value.is_a?(Array) ? value.first : value
+        return nil if str.nil?
+
+        str = str.strip
+
+        # Try integer seconds
+        if str =~ /\A\d+\z/
+          seconds = str.to_i
+          return seconds > 0 ? seconds : nil
+        end
+
+        # Try HTTP-date (RFC 7231 S7.1.1.1)
+        begin
+          target = Time.httpdate(str)
+          seconds = (target - Time.now).to_i
+          seconds > 0 ? seconds : nil
+        rescue ArgumentError
+          nil
         end
       end
 
-      # Sends a request for the batch, returns [status_code, body]
-      def send_request(write_key, batch)
+      # Sends a request for the batch, returns [status_code, body, headers]
+      def send_request(write_key, batch, retry_count = 0)
         payload = JSON.generate(
           :sentAt => datetime_in_iso8601(Time.now),
           :batch => batch
         )
-        request = Net::HTTP::Post.new(@path, @headers)
+        headers = @headers.dup
+        headers['X-Retry-Count'] = retry_count.to_s if retry_count > 0
+
+        request = Net::HTTP::Post.new(@path, headers)
         request.basic_auth(write_key, nil)
 
         if self.class.stub
           logger.debug "stubbed request to #{@path}: " \
             "write key = #{write_key}, batch = #{JSON.generate(batch)}"
 
-          [200, '{}']
+          [200, '{}', {}]
         else
-          @http.start unless @http.started? # Maintain a persistent connection
+          @http.start unless @http.started?
           response = @http.request(request, payload)
-          [response.code.to_i, response.body]
+          [response.code.to_i, response.body, response.to_hash]
         end
       end
 

data/lib/segment/analytics/version.rb

@@ -2,6 +2,6 @@
 
 module Segment
   class Analytics
-    VERSION = '2.5.0'
+    VERSION = '2.6.0'
   end
 end

data/lib/segment/analytics/worker.rb

@@ -45,7 +45,7 @@ module Segment
           end
 
           res = @transport.send @write_key, @batch
-          @on_error.call(res.status, res.error) unless res.status == 200
+          @on_error.call(res.status, res.error) unless res.success?
 
           @lock.synchronize { @batch.clear }
         end

data/lib/segment/analytics.rb

@@ -6,6 +6,7 @@ require 'segment/analytics/utils'
 require 'segment/analytics/field_parser'
 require 'segment/analytics/client'
 require 'segment/analytics/worker'
+require 'segment/analytics/retry_budget'
 require 'segment/analytics/transport'
 require 'segment/analytics/response'
 require 'segment/analytics/logging'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: analytics-ruby
 version: !ruby/object:Gem::Version
-  version: 2.5.0
+  version: 2.6.0
 platform: ruby
 authors:
 - Segment.io
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-10-07 00:00:00.000000000 Z
+date: 2026-09-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: commander
@@ -86,14 +86,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 3.6.2
+        version: '3.6'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 3.6.2
+        version: '3.6'
 - !ruby/object:Gem::Dependency
   name: rubocop
   requirement: !ruby/object:Gem::Requirement
@@ -126,6 +126,7 @@ files:
 - lib/segment/analytics/logging.rb
 - lib/segment/analytics/message_batch.rb
 - lib/segment/analytics/response.rb
+- lib/segment/analytics/retry_budget.rb
 - lib/segment/analytics/test_queue.rb
 - lib/segment/analytics/transport.rb
 - lib/segment/analytics/utils.rb
@@ -135,7 +136,7 @@ homepage: https://github.com/segmentio/analytics-ruby
 licenses:
 - MIT
 metadata: {}
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -150,8 +151,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.6
-signing_key: 
+rubygems_version: 3.5.22
+signing_key:
 specification_version: 4
 summary: Segment.io analytics library
 test_files: []