abmeter 0.2.4 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3de305080a86006a94e25c375c97e3f00130132ff44e4f1c51d7fb8719d0a18f
-  data.tar.gz: 2c318d9008614bb7b7ad561c7587cecbf009fa8e68331d6fc35974b8b1cd1ccd
+  metadata.gz: 2d4ea3bdc7addec399a8644a3d8d2ee8f0329b4d85b117a56f4df51c58e04816
+  data.tar.gz: b03e52a1fe306fe68b7dd63879ff067e59f358bdf885d4a8905e86d743ba282d
 SHA512:
-  metadata.gz: dc3b45f859392cb95ca923aa89f813b876ddb6d086852da649c8a7d7c53ab2f7c0564761d0eefb19525578395882af92d4af101e5de8e1210a2f26decbd12188
-  data.tar.gz: b4ac66c59f3d601e3f7b88bcdcbc0b64ac8daf7a48c0d96ed8d76dad0a5804644f53bbef3f848de6676f57ee18caa626bd0efd9035ba9db634bcc506091f727f
+  metadata.gz: 18f1020d7926f3e7026441877010f730ef7ffc06078ad738a7be0121c9399465d3b056e39b6d0133f97d32fced489bec9a6f26c9d99f4f817e223b8927260eaf
+  data.tar.gz: 9952d1a56ed63530d25200b21d88b0aaf3aec868752b72c46029e5905af5ff20af1eb45c472323afa20251694949ba9df0ff611d13a1633d0a110546d1aa41a5

data/README.md

@@ -2,6 +2,8 @@
 
 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**.
@@ -38,6 +40,18 @@ 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.

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

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

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

data/lib/abmeter.rb

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