abmeter 0.2.4 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3de305080a86006a94e25c375c97e3f00130132ff44e4f1c51d7fb8719d0a18f
-  data.tar.gz: 2c318d9008614bb7b7ad561c7587cecbf009fa8e68331d6fc35974b8b1cd1ccd
+  metadata.gz: f33d4944ddd5acac49f58a672004aa3460a7d8435a651ad6172d88960f02ebdb
+  data.tar.gz: b800e19818cc9d408380c14ae7e7fc2bad8d421839f970f14e259b327acb314c
 SHA512:
-  metadata.gz: dc3b45f859392cb95ca923aa89f813b876ddb6d086852da649c8a7d7c53ab2f7c0564761d0eefb19525578395882af92d4af101e5de8e1210a2f26decbd12188
-  data.tar.gz: b4ac66c59f3d601e3f7b88bcdcbc0b64ac8daf7a48c0d96ed8d76dad0a5804644f53bbef3f848de6676f57ee18caa626bd0efd9035ba9db634bcc506091f727f
+  metadata.gz: 83e08361797d68f6367b1651358557b25635e8a8554a9fb3e7dd79169f08b0c7443a52da385535cda59a25b4276cf9424c696dc4130c2a42f75e114412555f8b
+  data.tar.gz: e60a8479335b24cc3f57b24a5af553ad77b5a8451c3b8801650ca13721e3281cda29d9c54717f064393f1b6d816157bc6b84a83290e56bb4abcef4edb8c2bbf0

data/README.md

@@ -1,6 +1,8 @@
 # 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.
 
 ## Supported Ruby versions
 
@@ -20,22 +22,45 @@ 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
+```
+
+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 renedring code:
-user = ABMeter.user(id: current_user.id, email: current_user.email)
-text = ABMeter.param('welcome_text', user)
+```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; use `get_exposure` for the same resolution without submitting. Full guides live at [abmeter.ai](https://abmeter.ai).
+
+## Shutdown
+
+```ruby
+# Graceful — bounded blocking, flushes pending exposures/events.
+# Returns true on clean shutdown, false if the timeout elapsed.
+ABMeter.reset(timeout: 5.0)
 
-# 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})
+# Immediate — non-blocking, discards anything still queued.
+# Use only when the process is exiting *right now* and you cannot afford I/O.
+ABMeter.reset!
 ```
 
 ## Development

data/bin/generate_num_utils_parity_fixture.rb

@@ -0,0 +1,32 @@
+#!/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).
+#
+# Emits 1000 [salt, user_id, expected] triples where `expected` is the integer
+# returned by ABMeter::Core::Utils::NumUtils.to_percentage. The Python
+# 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_PATH = File.expand_path(
+  '../../sdk-python/tests/fixtures/num_utils_parity.json', __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
+
+File.write(FIXTURE_PATH, "#{JSON.pretty_generate(rows)}\n")
+puts "Wrote #{rows.size} rows to #{FIXTURE_PATH}"

data/lib/abmeter/async_submitter.rb

@@ -1,9 +1,12 @@
+require 'time' # Time#iso8601
+
 module ABMeter
   class AsyncSubmitter
     # Private internal constants for async submitter behavior
     BATCH_SIZE = 100
     MAX_SUBMIT_ATTEMPTS = 3
     MAX_RETRY_QUEUE_SIZE = 1000
+    DEFAULT_SHUTDOWN_TIMEOUT = 5.0 # seconds — max time a graceful shutdown blocks before killing the worker
 
     @queue = Queue.new
     @retry_queue = []
@@ -12,6 +15,9 @@ module ABMeter
     @worker_thread = nil
     @flush_interval = DEFAULT_FLUSH_INTERVAL
     @logger = nil
+    @stopping = false
+    @stop_mutex = Mutex.new
+    @stop_signal = ConditionVariable.new
 
     class << self
       attr_reader :api_client, :flush_interval, :logger, :retry_queue
@@ -63,20 +69,47 @@ module ABMeter
         end
       end
 
-      def shutdown
+      # Graceful, lossless, bounded blocking. Signals the worker to stop, which
+      # triggers a final flush of the main and retry queues, then waits up to
+      # `timeout` seconds for that flush to finish and the worker to exit. Kills
+      # the worker (dropping anything still unflushed) if the timeout elapses.
+      # Returns true on clean shutdown, false on timeout.
+      def shutdown(timeout: DEFAULT_SHUTDOWN_TIMEOUT)
+        worker = @worker_thread
+        return true unless worker
+
+        request_stop
+        joined = worker.join(timeout)
+        if joined.nil?
+          worker.kill
+          worker.join
+          log_error("Graceful shutdown timed out after #{timeout}s, killing worker (queued: #{@queue.size}, retry: #{@retry_queue.size})")
+        end
+        !joined.nil?
+      end
+
+      # Immediate, lossy, non-blocking. Kills the worker and discards queued
+      # items without any network I/O.
+      def shutdown!
         @worker_thread&.kill
-        # Flush all remaining exposures
-        flush until @queue.empty?
+        dropped_queue = @queue.size
+        dropped_retry = @retry_queue.size
+        if dropped_queue.positive? || dropped_retry.positive?
+          log_error("Immediate shutdown, dropping items (dropped_queue: #{dropped_queue}, dropped_retry: #{dropped_retry})")
+        end
+        true
+      end
+
+      def reset(timeout: DEFAULT_SHUTDOWN_TIMEOUT)
+        result = shutdown(timeout: timeout)
+        clear_state
+        result
       end
 
       def reset!
-        shutdown
-        @queue = Queue.new
-        @retry_queue = []
-        @api_client = nil
-        @worker_thread = nil
-        @flush_interval = DEFAULT_FLUSH_INTERVAL
-        @logger = nil
+        shutdown!
+        clear_state
+        true
       end
 
       def worker_alive?
@@ -92,17 +125,53 @@ module ABMeter
       def start_worker
         return if worker_alive?
 
+        @stopping = false
         @worker_thread = Thread.new do
-          loop do
-            sleep @flush_interval
-            flush
+          until @stopping
+            begin
+              wait_for_next_flush
+              flush unless @stopping
+            rescue StandardError => e
+              # Log error but keep worker running
+              log_error("Worker error: #{e.message}")
+            end
+          end
+          # Final drain on graceful stop — bounded by the caller's join timeout.
+          begin
+            flush until @queue.empty? && @retry_queue.empty?
           rescue StandardError => e
-            # Log error but keep worker running
-            log_error("Worker error: #{e.message}")
+            log_error("Final flush error: #{e.message}")
           end
         end
       end
 
+      # Sleeps for @flush_interval, waking immediately when request_stop
+      # signals. Re-checking @stopping under @stop_mutex closes the
+      # lost-wakeup window between the worker loop's flag check and the wait
+      # (a bare sleep + Thread#wakeup would drop a signal sent in that gap).
+      def wait_for_next_flush
+        @stop_mutex.synchronize do
+          @stop_signal.wait(@stop_mutex, @flush_interval) unless @stopping
+        end
+      end
+
+      def request_stop
+        @stop_mutex.synchronize do
+          @stopping = true
+          @stop_signal.broadcast
+        end
+      end
+
+      def clear_state
+        @queue = Queue.new
+        @retry_queue = []
+        @api_client = nil
+        @worker_thread = nil
+        @flush_interval = DEFAULT_FLUSH_INTERVAL
+        @logger = nil
+        @stopping = false
+      end
+
       def submit_exposures(exposures)
         submit_batch(:exposure, exposures) { |exposures| @api_client.submit_exposures(exposures) }
       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/experiment.rb

@@ -43,6 +43,7 @@ module ABMeter
           {
             id: id,
             space_id: space_id,
+            salt: salt,
             range: [range.begin, range.end],
             audience_variants: audience_variants.map do |audience_variant|
               {

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/version.rb

@@ -1,3 +1,3 @@
 module ABMeter
-  VERSION = '0.2.4'.freeze
+  VERSION = '0.4.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
 
@@ -64,12 +70,25 @@ module ABMeter
       end
     end
 
-    def reset!
-      AsyncSubmitter.shutdown
+    # Graceful, lossless, bounded blocking. Flushes pending exposures/events
+    # before clearing state. Returns true on clean shutdown, false if the
+    # timeout elapsed and the worker had to be killed.
+    def reset(timeout: AsyncSubmitter::DEFAULT_SHUTDOWN_TIMEOUT)
+      result = AsyncSubmitter.reset(timeout: timeout)
+      @config = nil
+      @client = nil
+      @resolver_provider = nil
+      result
+    end
 
+    # Immediate, lossy, non-blocking. Kills the worker thread and discards
+    # queued exposures/events without any network I/O.
+    def reset!
+      AsyncSubmitter.reset!
       @config = nil
       @client = nil
       @resolver_provider = nil
+      nil
     end
 
     def track_event(event_name, user_id, data)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: abmeter
 version: !ruby/object:Gem::Version
-  version: 0.2.4
+  version: 0.4.0
 platform: ruby
 authors:
 - ABMeter
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-06-13 00:00:00.000000000 Z
+date: 2026-07-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -49,6 +49,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 +72,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: