abmeter 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f33d4944ddd5acac49f58a672004aa3460a7d8435a651ad6172d88960f02ebdb
-  data.tar.gz: b800e19818cc9d408380c14ae7e7fc2bad8d421839f970f14e259b327acb314c
+  metadata.gz: 127c157ec200964f199fb170d036d9b9898f717a1634002d02dcd211c3296387
+  data.tar.gz: 9774017d52cf7b9925eddd837fd4972a693cfd5b76f11c4fe20bd8692d85ddec
 SHA512:
-  metadata.gz: 83e08361797d68f6367b1651358557b25635e8a8554a9fb3e7dd79169f08b0c7443a52da385535cda59a25b4276cf9424c696dc4130c2a42f75e114412555f8b
-  data.tar.gz: e60a8479335b24cc3f57b24a5af553ad77b5a8451c3b8801650ca13721e3281cda29d9c54717f064393f1b6d816157bc6b84a83290e56bb4abcef4edb8c2bbf0
+  metadata.gz: 6174b2a6d2308658310f5a2f35df3d3a986f0979b2a87cd318b3f051469074fa1cf2ead76a53b4a18569dd50d28181b6bdde256c9086be27612e3e12525efa32
+  data.tar.gz: eee251586f7279d59edbb6049e5265156afd1858383752dfb4c280d97dc32dd04543c2e44cf8e8f9348046194ec6bcf5b91c651299a0b53e17716e0fdd069ca6

data/README.md

@@ -49,7 +49,7 @@ text = ABMeter.resolve_parameter(user: user, parameter_slug: 'welcome_text')
 ABMeter.track_event('user_purchases_plan', current_user.id, { plan: purchased_plan.name, price: purchased_plan.price })
 ```
 
-The two calls are one loop: the experiment varies `welcome_text`, and the event feeds a metric whose effect the experiment measures across variants. Note that `resolve_parameter` is **not** a pure read — it resolves the value locally and records an exposure in the background; use `get_exposure` for the same resolution without submitting. Full guides live at [abmeter.ai](https://abmeter.ai).
+The two calls are one loop: the experiment varies `welcome_text`, and the event feeds a metric whose effect the experiment measures across variants. Note that `resolve_parameter` is **not** a pure read — it resolves the value locally and records an exposure in the background. Full guides live at [abmeter.ai](https://abmeter.ai).
 
 ## Shutdown
 

data/bin/generate_num_utils_parity_fixture.rb

@@ -1,11 +1,12 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
-# Regenerates the cross-language num-utils parity fixture consumed by the
-# Python SDK (sdk-python/tests/test_num_utils_parity.py).
+# Regenerates the cross-language num-utils parity fixture consumed by every
+# ported SDK (sdk-python/tests/test_num_utils_parity.py,
+# sdk-node/tests/num-utils-parity.test.ts).
 #
 # Emits 1000 [salt, user_id, expected] triples where `expected` is the integer
-# returned by ABMeter::Core::Utils::NumUtils.to_percentage. The Python
+# returned by ABMeter::Core::Utils::NumUtils.to_percentage. Each ported
 # implementation must reproduce every row. Run from the abmeter-sdk directory:
 #
 #   bundle exec ruby bin/generate_num_utils_parity_fixture.rb
@@ -15,9 +16,10 @@
 require 'json'
 require_relative '../lib/abmeter/core/utils/num_utils'
 
-FIXTURE_PATH = File.expand_path(
-  '../../sdk-python/tests/fixtures/num_utils_parity.json', __dir__
-)
+FIXTURE_PATHS = [
+  '../../sdk-python/tests/fixtures/num_utils_parity.json',
+  '../../sdk-node/tests/fixtures/num_utils_parity.json'
+].map { |path| File.expand_path(path, __dir__) }
 ROW_COUNT = 1000
 
 rows = Array.new(ROW_COUNT) do |i|
@@ -28,5 +30,7 @@ rows = Array.new(ROW_COUNT) do |i|
   [salt, user_id, ABMeter::Core::Utils::NumUtils.to_percentage(salt, user_id)]
 end
 
-File.write(FIXTURE_PATH, "#{JSON.pretty_generate(rows)}\n")
-puts "Wrote #{rows.size} rows to #{FIXTURE_PATH}"
+FIXTURE_PATHS.each do |path|
+  File.write(path, "#{JSON.pretty_generate(rows)}\n")
+  puts "Wrote #{rows.size} rows to #{path}"
+end

data/lib/abmeter/api_error.rb

@@ -2,10 +2,16 @@ require 'active_support/core_ext/hash/indifferent_access'
 
 module ABMeter
   class APIError < StandardError
-    attr_reader :code, :details, :status
+    RATE_LIMITED_STATUS = 429
+    DEFAULT_RETRY_AFTER = 30 # seconds, when a 429 has no usable Retry-After
+    MIN_RETRY_AFTER = 1 # seconds, so a zero cannot spin a drain loop
+    MAX_RETRY_AFTER = 600 # seconds, the API's rate-limit window
+
+    attr_reader :code, :details, :status, :retry_after
 
     def initialize(response)
       @status = response.status
+      @retry_after = parse_retry_after(response.headers['Retry-After']) if rate_limited?
       error_body = response.body
 
       if error_body.is_a?(Hash)
@@ -39,6 +45,10 @@ module ABMeter
       @status >= 500 || @status == 408 || @status == 429
     end
 
+    def rate_limited?
+      @status == RATE_LIMITED_STATUS
+    end
+
     def partial_failure?
       @status == 400 && @details.is_a?(Hash) && !@details[:failures].nil? && !@details[:failures].empty?
     end
@@ -46,5 +56,15 @@ module ABMeter
     def failure_count
       @details&.dig(:invalid_count) || 0
     end
+
+    private
+
+    # Retry-After as delta-seconds only; the API never sends an HTTP date.
+    def parse_retry_after(value)
+      seconds = Integer(value.to_s.strip, 10, exception: false)
+      return DEFAULT_RETRY_AFTER if seconds.nil? || seconds.negative?
+
+      seconds.clamp(MIN_RETRY_AFTER, MAX_RETRY_AFTER)
+    end
   end
 end

data/lib/abmeter/async_submitter.rb

@@ -18,6 +18,7 @@ module ABMeter
     @stopping = false
     @stop_mutex = Mutex.new
     @stop_signal = ConditionVariable.new
+    @paused_until = nil
 
     class << self
       attr_reader :api_client, :flush_interval, :logger, :retry_queue
@@ -48,7 +49,10 @@ module ABMeter
                     })
       end
 
+      # A no-op while a 429 pause lasts: new items wait in the main queue.
       def flush
+        return if paused?
+
         items = []
 
         @mutex.synchronize do
@@ -56,7 +60,7 @@ module ABMeter
           process_retry_queue
 
           # Then process new items
-          items << @queue.pop while !@queue.empty? && items.size < BATCH_SIZE
+          items << @queue.pop while !paused? && !@queue.empty? && items.size < BATCH_SIZE
         end
 
         # Group by type and submit
@@ -120,6 +124,10 @@ module ABMeter
         @queue.size
       end
 
+      def paused?
+        !@paused_until.nil? && monotonic_now < @paused_until
+      end
+
       private
 
       def start_worker
@@ -138,7 +146,10 @@ module ABMeter
           end
           # Final drain on graceful stop — bounded by the caller's join timeout.
           begin
-            flush until @queue.empty? && @retry_queue.empty?
+            until @queue.empty? && @retry_queue.empty?
+              wait_out_pause
+              flush
+            end
           rescue StandardError => e
             log_error("Final flush error: #{e.message}")
           end
@@ -155,6 +166,11 @@ module ABMeter
         end
       end
 
+      def wait_out_pause
+        remaining = @paused_until.to_f - monotonic_now
+        sleep(remaining) if remaining.positive?
+      end
+
       def request_stop
         @stop_mutex.synchronize do
           @stopping = true
@@ -170,6 +186,7 @@ module ABMeter
         @flush_interval = DEFAULT_FLUSH_INTERVAL
         @logger = nil
         @stopping = false
+        @paused_until = nil
       end
 
       def submit_exposures(exposures)
@@ -188,10 +205,18 @@ module ABMeter
           return
         end
 
+        if paused?
+          add_to_retry_queue(type, items)
+          return
+        end
+
         yield items
         # Success - nothing to do
       rescue ABMeter::APIError => e
-        if e.retryable?
+        if e.rate_limited?
+          pause_submissions(e.retry_after, type, items.size)
+          add_to_retry_queue(type, items)
+        elsif e.retryable?
           log_error("Retryable error submitting #{items.size} #{type}s: #{e.message}")
           add_to_retry_queue(type, items)
         elsif e.partial_failure?
@@ -209,21 +234,23 @@ module ABMeter
 
       def add_to_retry_queue(type, items)
         @mutex.synchronize do
-          items.each do |item|
-            # Only add if we haven't exceeded max queue size
-            if @retry_queue.size < MAX_RETRY_QUEUE_SIZE
-              @retry_queue << {
-                type: type,
-                data: item,
-                attempts: 0
-              }
-            else
-              log_error("Retry queue full, dropping #{type}")
-            end
-          end
+          room = MAX_RETRY_QUEUE_SIZE - @retry_queue.size
+          kept = items.first([room, 0].max)
+          @retry_queue.concat(kept.map { |item| { type: type, data: item, attempts: 0 } })
+          dropped = items.size - kept.size
+          log_error("Retry queue full, dropping #{dropped} #{type}s") if dropped.positive?
         end
       end
 
+      def pause_submissions(seconds, type, count)
+        @paused_until = monotonic_now + seconds
+        log_warn("Rate limited, pausing submissions for #{seconds}s (#{count} #{type}s held for retry)")
+      end
+
+      def monotonic_now
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+
       def process_retry_queue
         return if @retry_queue.empty?
 
@@ -249,6 +276,8 @@ module ABMeter
 
       def process_retry_batch(type, items)
         return [] if items.empty?
+        # Held, not attempted: a pause set earlier in this flush.
+        return items if paused?
 
         # Increment attempts and filter out max retries
         active_items = items.filter_map do |item|
@@ -269,7 +298,12 @@ module ABMeter
           yield data
           [] # Success - return empty array
         rescue ABMeter::APIError => e
-          if e.retryable?
+          if e.rate_limited?
+            pause_submissions(e.retry_after, type, data.size)
+            # The wait is not an attempt.
+            active_items.each { |item| item[:attempts] -= 1 }
+            active_items
+          elsif e.retryable?
             log_error("Retry failed with retryable error for #{data.size} #{type}s: #{e.message}")
             active_items # Return all items for retry
           elsif e.partial_failure?
@@ -291,9 +325,11 @@ module ABMeter
       end
 
       def log_error(message)
-        return unless @logger
+        @logger&.error("AsyncSubmitter: #{message}")
+      end
 
-        @logger.error("AsyncSubmitter: #{message}")
+      def log_warn(message)
+        @logger&.warn("AsyncSubmitter: #{message}")
       end
     end
 

data/lib/abmeter/client.rb

@@ -44,6 +44,8 @@ module ABMeter
         f.request :json
         f.response :json
         f.headers['Authorization'] = "Bearer #{@api_key}"
+        f.options.timeout = DEFAULT_REQUEST_TIMEOUT
+        f.options.open_timeout = DEFAULT_REQUEST_TIMEOUT
         f.adapter Faraday.default_adapter
       end
     end

data/lib/abmeter/constants.rb

@@ -8,4 +8,5 @@ module ABMeter
   DEFAULT_MAX_SUBMIT_ATTEMPTS = 3
   DEFAULT_MAX_RETRY_QUEUE_SIZE = 1000
   DEFAULT_LOG_LEVEL = :error
+  DEFAULT_REQUEST_TIMEOUT = 30 # seconds
 end

data/lib/abmeter/resolver_provider.rb

@@ -1,16 +1,22 @@
+require_relative 'error_safety'
+
 module ABMeter
   class ResolverProvider
+    include ErrorSafety
+
     attr_reader :last_fetched_at
 
     def initialize(config:, api_client: nil)
       raise 'Either api_key or static_config must be provided' unless config.api_key || config.static_config
 
+      @config = config
       @api_client = api_client
       @json_config = config.static_config
       @fetch_interval = config.fetch_interval
 
       @resolver = nil
       @last_fetched_at = nil
+      @last_attempted_at = nil
 
       # Build resolver immediately if using JSON config
       @resolver = ABMeter::Core.build_resolver_from_json(@json_config) if @json_config
@@ -41,14 +47,23 @@ module ABMeter
     def refresh_config_if_needed
       return if @json_config # No refresh needed for JSON config
 
-      update_resolver if !@resolver || time_to_refresh_config?
+      return unless !@resolver || time_to_refresh_config?
+
+      begin
+        update_resolver
+      rescue StandardError => e
+        raise unless @resolver
+
+        serve_last_known_config(e)
+      end
     end
 
     def time_to_refresh_config?
-      @last_fetched_at.nil? || (Time.now - @last_fetched_at > @fetch_interval)
+      @last_attempted_at.nil? || (Time.now - @last_attempted_at > @fetch_interval)
     end
 
     def update_resolver
+      @last_attempted_at = Time.now
       response = @api_client.get_assignment_config
       config_data = response[:config]
 
@@ -56,6 +71,11 @@ module ABMeter
       @last_fetched_at = Time.now
     end
 
+    def serve_last_known_config(error)
+      log_error('Failed to refresh assignment config, serving last known config', error)
+      call_error_callback(error)
+    end
+
     def queue_exposure(exposure)
       AsyncSubmitter.queue_exposure(exposure)
     end

data/lib/abmeter/version.rb

@@ -1,3 +1,3 @@
 module ABMeter
-  VERSION = '0.4.0'.freeze
+  VERSION = '0.5.0'.freeze
 end

data/lib/abmeter.rb

@@ -48,7 +48,6 @@ module ABMeter
       config.base_url = DEFAULT_BASE_URL
       yield(config)
       config.validate!
-      # Set logger level if both logger and log_level are configured
       config.send(:set_logger_level, config.log_level)
       @config = config
 
@@ -126,13 +125,13 @@ module ABMeter
 
     # Logging and error handling
     attr_accessor :logger         # Logger instance (auto-detected by default)
-    attr_accessor :log_level      # Log level (:debug, :info, :warn, :error)
+    attr_accessor :log_level      # Level for the SDK's own logger; a logger you pass in keeps its level
     attr_accessor :error_callback # Proc called on errors
 
     def initialize
       @flush_interval = DEFAULT_FLUSH_INTERVAL
       @fetch_interval = DEFAULT_FETCH_INTERVAL
-      @logger = detect_logger
+      @logger = host_logger || (@own_logger = build_own_logger)
     end
 
     def validate!
@@ -161,13 +160,13 @@ module ABMeter
     private
 
     def set_logger_level(log_level)
-      return unless @logger
+      return unless @own_logger && @logger.equal?(@own_logger)
 
-      @logger.level = logger_level_for(@logger, log_level || DEFAULT_LOG_LEVEL) if @logger.respond_to?(:level=)
+      @own_logger.level = logger_level_for(@own_logger, log_level || DEFAULT_LOG_LEVEL)
     end
 
     def logger_level_for(logger, log_level)
-      if defined?(Logger) && (logger.is_a?(Logger) || (defined?(Rails) && logger == Rails.logger))
+      if defined?(Logger) && logger.is_a?(Logger)
         return case log_level
                when :debug then Logger::DEBUG
                when :info then Logger::INFO
@@ -181,18 +180,15 @@ module ABMeter
       @log_level
     end
 
-    def detect_logger
-      # Try Rails logger first
-      if defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
-        Rails.logger
-      # Try Semantic Logger
-      elsif defined?(SemanticLogger)
-        SemanticLogger['ABMeter']
-      # Default to Ruby's Logger
-      else
-        require 'logger'
-        Logger.new($stdout, progname: 'ABMeter')
-      end
+    def host_logger
+      Rails.logger if defined?(Rails) && Rails.respond_to?(:logger)
+    end
+
+    def build_own_logger
+      return SemanticLogger['ABMeter'] if defined?(SemanticLogger)
+
+      require 'logger'
+      Logger.new($stdout, progname: 'ABMeter')
     end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: abmeter
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - ABMeter
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-07-25 00:00:00.000000000 Z
+date: 2026-11-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -41,7 +41,6 @@ dependencies:
 description: ABMeter SDK is a client library for interacting with the ABMeter testing
   service
 email:
-- info@abmeter.com
 executables: []
 extensions: []
 extra_rdoc_files: []