abmeter 0.2.2 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9942da1ef58cb41f5dd91e2bf4324394a393b9c5b8846c361389227c60b54c86
-  data.tar.gz: 8be692e8ecf838466c7a1def6efbdae4b20af23105257b41b44b693fcf846dfe
+  metadata.gz: 2d4ea3bdc7addec399a8644a3d8d2ee8f0329b4d85b117a56f4df51c58e04816
+  data.tar.gz: b03e52a1fe306fe68b7dd63879ff067e59f358bdf885d4a8905e86d743ba282d
 SHA512:
-  metadata.gz: 129b61ca52cee9e0d281d9be91813a2ecc96e7044124c3e1f0f21aeedd3b35a8ee089d03ad0a176cf94bee730d7beeb9c4ee3484c48bf30cfb3a1cedf6e4be19
-  data.tar.gz: c0601c6055cb0767e812890d1830429667c143d8a8a6d21f3928832c6a8bb3a99c1063db6a20ca6c26d49b6d104922fa1539660cfd17ea7e15aec1a56e089e3e
+  metadata.gz: 18f1020d7926f3e7026441877010f730ef7ffc06078ad738a7be0121c9399465d3b056e39b6d0133f97d32fced489bec9a6f26c9d99f4f817e223b8927260eaf
+  data.tar.gz: 9952d1a56ed63530d25200b21d88b0aaf3aec868752b72c46029e5905af5ff20af1eb45c472323afa20251694949ba9df0ff611d13a1633d0a110546d1aa41a5

data/README.md

@@ -2,6 +2,12 @@
 
 A simple A/B testing client library for Ruby applications.
 
+> **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
+
+`abmeter` supports **Ruby 3.2 and newer**.
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -34,6 +40,32 @@ 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})
 ```
 
+## Shutdown
+
+```ruby
+# Graceful — bounded blocking, flushes pending exposures/events.
+# Returns true on clean shutdown, false if the timeout elapsed.
+ABMeter.reset(timeout: 5.0)
+
+# 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
+
+The gem uses [mise](https://mise.jdx.dev/) to pin Ruby (`mise.toml`). Pure-Ruby — no Postgres / Redis required.
+
+```bash
+brew install mise            # one-time
+mise install                 # one-time: install pinned Ruby
+bundle install
+bundle exec rspec            # tests
+bundle exec rubocop          # lint (if .rubocop.yml present)
+```
+
+The gem is tested against Ruby 3.2, 3.3, 3.4, and 4.0.
+
 ## License
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT). 

data/lib/abmeter/async_submitter.rb

@@ -4,6 +4,7 @@ module ABMeter
     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 +13,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 +67,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 +123,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/experiment.rb

@@ -8,7 +8,9 @@ module ABMeter
 
         attr_reader :id, :range, :audience_variants, :space_id, :salt, :space_salt
 
-        def initialize(id:, range:, audience_variants:, space_id:, salt:, space_salt:)
+        # The six keyword args are this value object's assignment inputs; a
+        # params object would only add indirection for a plain data holder.
+        def initialize(id:, range:, audience_variants:, space_id:, salt:, space_salt:) # rubocop:disable Metrics/ParameterLists
           @id = id
           @range = range
           @audience_variants = audience_variants
@@ -41,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/variant.rb

@@ -16,7 +16,7 @@ module ABMeter
         end
 
         def self.from_json(variant)
-          parameter_values = variant[:parameter_values].map { |pv| [pv[:slug], pv[:value]] }.to_h
+          parameter_values = variant[:parameter_values].to_h { |pv| [pv[:slug], pv[:value]] }
           Variant.new(id: variant[:id], parameter_values: parameter_values)
         end
 

data/lib/abmeter/core/utils/num_utils.rb

@@ -33,7 +33,7 @@ module ABMeter
           # Formula: (num * range) >> bits = (num * 100) >> 64
           # This maps [0, 2^64) uniformly to [0, 100)
           percentage = (num * 100) >> 64
-          
+
           # Add 1 to get 1-100 range instead of 0-99
           percentage + 1
         end

data/lib/abmeter/core.rb

@@ -1,6 +1,5 @@
 # frozen_string_literal: true
 
-require 'ostruct'
 require_relative 'version'
 
 # Utils

data/lib/abmeter/version.rb

@@ -1,3 +1,3 @@
 module ABMeter
-  VERSION = '0.2.2'.freeze
+  VERSION = '0.3.0'.freeze
 end

data/lib/abmeter.rb

@@ -1,6 +1,5 @@
 require 'active_support/core_ext/hash/indifferent_access'
 require 'digest'
-require 'ostruct'
 
 # Core (zero-dependency assignment logic)
 require_relative 'abmeter/core'
@@ -17,6 +16,7 @@ require_relative 'abmeter/error_safety'
 module ABMeter
   class << self
     include ErrorSafety
+
     def config
       raise 'ABMeter not configured. Call ABMeter.configure { |config| ... } first.' unless @config
 
@@ -64,12 +64,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,13 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: abmeter
 version: !ruby/object:Gem::Version
-  version: 0.2.2
+  version: 0.3.0
 platform: ruby
 authors:
 - ABMeter
+autorequire:
 bindir: bin
 cert_chain: []
-date: 1980-01-02 00:00:00.000000000 Z
+date: 2026-07-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -77,6 +78,7 @@ metadata:
   homepage_uri: https://github.com/abmeter/abmeter-ruby
   source_code_uri: https://github.com/abmeter/abmeter-ruby
   rubygems_mfa_required: 'true'
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -91,7 +93,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 3.5.22
+signing_key:
 specification_version: 4
 summary: ABMeter SDK for feature flags and A/B testing
 test_files: []