abmeter 0.3.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2d4ea3bdc7addec399a8644a3d8d2ee8f0329b4d85b117a56f4df51c58e04816
-  data.tar.gz: b03e52a1fe306fe68b7dd63879ff067e59f358bdf885d4a8905e86d743ba282d
+  metadata.gz: 127c157ec200964f199fb170d036d9b9898f717a1634002d02dcd211c3296387
+  data.tar.gz: 9774017d52cf7b9925eddd837fd4972a693cfd5b76f11c4fe20bd8692d85ddec
 SHA512:
-  metadata.gz: 18f1020d7926f3e7026441877010f730ef7ffc06078ad738a7be0121c9399465d3b056e39b6d0133f97d32fced489bec9a6f26c9d99f4f817e223b8927260eaf
-  data.tar.gz: 9952d1a56ed63530d25200b21d88b0aaf3aec868752b72c46029e5905af5ff20af1eb45c472323afa20251694949ba9df0ff611d13a1633d0a110546d1aa41a5
+  metadata.gz: 6174b2a6d2308658310f5a2f35df3d3a986f0979b2a87cd318b3f051469074fa1cf2ead76a53b4a18569dd50d28181b6bdde256c9086be27612e3e12525efa32
+  data.tar.gz: eee251586f7279d59edbb6049e5265156afd1858383752dfb4c280d97dc32dd04543c2e44cf8e8f9348046194ec6bcf5b91c651299a0b53e17716e0fdd069ca6

data/README.md

@@ -1,6 +1,6 @@
 # ABMeter Gem
 
-A simple A/B testing client library for Ruby applications.
+[ABMeter](https://abmeter.ai) is a feature-flag and A/B-testing platform. You define parameters, experiments, and feature flags in the ABMeter Lab; this gem reads the value assigned to each user in your Ruby app and reports events back.
 
 > **Breaking change in 0.3.0:** `ABMeter.reset!` now discards queued data without any network I/O; use `ABMeter.reset` for the previous drain-on-exit behavior.
 
@@ -22,24 +22,35 @@ And then execute:
 $ bundle install
 ```
 
+## Getting an API key
+
+Sign up at [abmeter.ai](https://abmeter.ai), then in the **Lab** open **API Keys** and create one. Expose it to your app (e.g. as `ABMETER_API_KEY`).
+
 ## Usage
 
+Configure the client once at startup:
+
 ```ruby
-# configure the client
 ABMeter.configure do |config|
   config.api_key = ENV['ABMETER_API_KEY']
 end
+```
 
-# Somewhere in the renedring code:
-user = ABMeter.user(id: current_user.id, email: current_user.email)
-text = ABMeter.param('welcome_text', user)
+The example below assumes a parameter `welcome_text` (in a space, with a variant, controlled by a running experiment or feature flag) and an event type `user_purchases_plan` already exist — create them through the ABMeter API or, more easily, your AI assistant over MCP. Until they do, `resolve_parameter` just returns the parameter's default and `track_event` rejects unknown event types.
 
-# Somewhere in the model code:
-current_user.plan = purchased_plan.name
-user = ABMeter.user(id: current_user.id, email: current_user.email)
-ABMeter.event(`user_purchases_plan`, user, {plan: purchased_plan.name, price: purchased_plan.price})
+```ruby
+# In request handling: read the value assigned to this user. `user_id` is the
+# only required field; an optional `email:` is available for predicate-based
+# (email-pattern) audience targeting.
+user = ABMeter::User.new(user_id: current_user.id)
+text = ABMeter.resolve_parameter(user: user, parameter_slug: 'welcome_text')
+
+# In business logic: record an action that feeds a metric.
+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. Full guides live at [abmeter.ai](https://abmeter.ai).
+
 ## Shutdown
 
 ```ruby

data/bin/generate_num_utils_parity_fixture.rb

@@ -0,0 +1,36 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# 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. Each ported
+# implementation must reproduce every row. Run from the abmeter-sdk directory:
+#
+#   bundle exec ruby bin/generate_num_utils_parity_fixture.rb
+#
+# Regenerate only when the assignment algorithm changes (it shouldn't).
+
+require 'json'
+require_relative '../lib/abmeter/core/utils/num_utils'
+
+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|
+  # Deterministic, varied inputs — mixed shapes exercise the hashing across
+  # salts and user-id formats without depending on RNG.
+  salt = "space-salt-#{i}-#{format('%04d', (i * 7) % 9973)}"
+  user_id = "user_#{((i * 31) + 5) % 100_003}"
+  [salt, user_id, ABMeter::Core::Utils::NumUtils.to_percentage(salt, user_id)]
+end
+
+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

@@ -1,3 +1,5 @@
+require 'time' # Time#iso8601
+
 module ABMeter
   class AsyncSubmitter
     # Private internal constants for async submitter behavior
@@ -16,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
@@ -46,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
@@ -54,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
@@ -118,6 +124,10 @@ module ABMeter
         @queue.size
       end
 
+      def paused?
+        !@paused_until.nil? && monotonic_now < @paused_until
+      end
+
       private
 
       def start_worker
@@ -136,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
@@ -153,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
@@ -168,6 +186,7 @@ module ABMeter
         @flush_interval = DEFAULT_FLUSH_INTERVAL
         @logger = nil
         @stopping = false
+        @paused_until = nil
       end
 
       def submit_exposures(exposures)
@@ -186,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?
@@ -207,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?
 
@@ -247,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|
@@ -267,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?
@@ -289,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/core/assignment_config/audience.rb

@@ -64,6 +64,8 @@ module ABMeter
         end
 
         def matches?(user)
+          return false if user.email.nil?
+
           user.email.match?(predicate)
         end
 

data/lib/abmeter/core/assignment_config/exposable.rb

@@ -7,7 +7,11 @@ module ABMeter
         protected
 
         def resolve_parameter_value(parameter, variant)
-          variant&.parameter_value(parameter.slug) || parameter.default_value
+          # Fall back to the default only when the variant does not set this
+          # parameter (nil). An explicitly-set falsy value (false, 0, "") is a
+          # real override and must win — `||` would wrongly drop a Boolean false.
+          value = variant&.parameter_value(parameter.slug)
+          value.nil? ? parameter.default_value : value
         end
 
         def validate_expose_parameter_args!(user_id, parameter, audience)

data/lib/abmeter/core/user.rb

@@ -5,7 +5,7 @@ module ABMeter
     class User
       attr_reader :user_id, :email
 
-      def initialize(user_id:, email:)
+      def initialize(user_id:, email: nil)
         @user_id = user_id
         @email = email
       end

data/lib/abmeter/core/user_parameter_resolver.rb

@@ -43,7 +43,6 @@ module ABMeter
 
       def validate_user!(user)
         raise ArgumentError, 'User must have user_id' unless user.respond_to?(:user_id)
-        raise ArgumentError, 'User must have email' unless user.respond_to?(:email)
       end
 
       def find_matching_feature_flag(user, parameter_slug)

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.3.0'.freeze
+  VERSION = '0.5.0'.freeze
 end

data/lib/abmeter.rb

@@ -14,6 +14,12 @@ require_relative 'abmeter/async_submitter'
 require_relative 'abmeter/error_safety'
 
 module ABMeter
+  # Top-level alias for the canonical user value object. Lets callers write
+  # `ABMeter::User.new(user_id: ...)` instead of reaching into `Core::User`,
+  # mirroring `abmeter.User(...)` in the Python SDK. Same class object, so
+  # `is_a?`/`===`/`instance_of?` keep working; `Core::User` stays canonical.
+  User = Core::User
+
   class << self
     include ErrorSafety
 
@@ -42,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
 
@@ -120,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!
@@ -155,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
@@ -175,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.3.0
+  version: 0.5.0
 platform: ruby
 authors:
 - ABMeter
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-07-03 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: []
@@ -49,6 +48,7 @@ files:
 - LICENSE.txt
 - README.md
 - bin/console
+- bin/generate_num_utils_parity_fixture.rb
 - bin/rspec
 - lib/abmeter.rb
 - lib/abmeter/api_error.rb
@@ -71,11 +71,11 @@ files:
 - lib/abmeter/error_safety.rb
 - lib/abmeter/resolver_provider.rb
 - lib/abmeter/version.rb
-homepage: https://github.com/abmeter/abmeter-ruby
+homepage: https://abmeter.ai
 licenses:
 - MIT
 metadata:
-  homepage_uri: https://github.com/abmeter/abmeter-ruby
+  homepage_uri: https://abmeter.ai
   source_code_uri: https://github.com/abmeter/abmeter-ruby
   rubygems_mfa_required: 'true'
 post_install_message: