posthog-ruby 3.21.0 → 3.22.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4ae3a78450df91e2e4cb88cd69a58e167cdb291dcc02f8ab446e3b0975c270eb
-  data.tar.gz: b912b023ed02a37004cfbe22511437ee4df2a5ec63799d6d47e6f6aa9fc4f164
+  metadata.gz: b47ba497bca9801a2d3a530351c021a9441368b63c16cebb2e04dcfe7d0d3b21
+  data.tar.gz: ab1cb2e8238e5f19e3d9c33d96386c98478e357d7bdb96121d8332910f61477a
 SHA512:
-  metadata.gz: 42b8b2587ee825e9a5446def45d11940b52a3a2203828b4506b2a4e1c28e2deefd61406df6ab33800bf1055c1475130554d6edef55a1498b478c43a30591f7b0
-  data.tar.gz: 4eec6bdd11abbeee85720d2a68872ad366f39b5c9c28ce72fd96aaf54f3098218578ccac954e35fe01099975d6f5a2afcfe5016b4460520a6341e465f026ed99
+  metadata.gz: cc57a456ab1f6ecdce0508ccea5a5896e42901938e8eb8d29b2f8ec07bd1a16c069030feed87aa196a604fffd2e3d0e40999f12434dca839e3aa507f008afdb7
+  data.tar.gz: d4c2693b6a8c60706707599d2958cdf24c54aa21f4ee8d067fbdae1cf9624fad08c923d95e67c5a629cd69aaee420e221a1d7edc51422d644bef8e4218d60b66

data/lib/posthog/client.rb

@@ -143,7 +143,10 @@ module PostHog
       @max_queue_size = opts[:max_queue_size] || Defaults::Queue::MAX_SIZE
       @worker_mutex = Mutex.new
       @shutdown_mutex = Mutex.new
+      @shutdown_condition = ConditionVariable.new
       @shutdown = false
+      @shutdown_complete = false
+      @shutdown_result = false
       @sync_mode = opts[:sync_mode] == true && !opts[:test_mode] && !@disabled
       @on_error = opts[:on_error] || proc { |status, error| }
       @worker = if opts[:test_mode] || @disabled
@@ -209,29 +212,40 @@ module PostHog
       @deprecation_emitted_for = Concurrent::Set.new
     end
 
-    # Synchronously waits until the worker has cleared the queue.
+    # When sync_mode is enabled, blocks until in-flight requests are complete
+    # and returns true. Timeout parameter has no effect.
     #
-    # Use only for scripts which are not long-running, and will specifically
-    # exit.
+    # Otherwise, waits until the worker has cleared the queue or timeout is hit.
+    # Note: The asynchronous wait polls and can be starved if another thread is
+    # actively continuing to enqueue new events.
     #
-    # @return [void]
-    def flush
+    # @param timeout [Numeric, nil] Maximum seconds to wait for pending events
+    #   to be sent, or +nil+ to wait indefinitely.
+    # @return [Boolean] +true+ if all pending events were sent, +false+ if the
+    #   timeout elapsed first.
+    def flush(timeout: nil)
       if @sync_mode
         # Wait for any in-flight sync send to complete
         @sync_lock.synchronize {} # rubocop:disable Lint/EmptyBlock
-        return
+        return true
       end
 
       if @worker.is_a?(NoopWorker)
         clear
-        return
+        return true
       end
 
+      deadline = timeout && (monotonic_time + timeout)
+
       while !@queue.empty? || @worker.is_requesting?
         ensure_worker_running
         @worker.request_flush
-        sleep(0.1)
+        remaining = deadline && (deadline - monotonic_time)
+        return false if remaining && remaining <= 0
+
+        sleep(remaining ? remaining.clamp(0, 0.1) : 0.1)
       end
+      true
     end
 
     # Clears the queue without waiting.
@@ -862,29 +876,65 @@ module PostHog
 
     # Flush pending events and stop background resources.
     #
-    # @return [void]
-    def shutdown
-      already_shutdown = @shutdown_mutex.synchronize do
+    # When sync_mode is not set, this method calls the flush method; see flush
+    # method documentation for timeout semantics. Unlike flush, this method
+    # stops the worker. So any events still queued after the timeout will not be
+    # sent. After the timeout, this method may wait up to one additional second
+    # for worker and transport cleanup, which may continue after it returns.
+    #
+    # @param timeout [Numeric, nil] Maximum seconds to wait for pending events
+    #   to be sent, or +nil+ to wait indefinitely. Has no effect when sync_mode
+    #   is true.
+    # @return [Boolean] +true+ if all pending events were sent, +false+ if the
+    #   timeout elapsed first.
+    def shutdown(timeout: nil)
+      deadline = timeout && (monotonic_time + timeout)
+      shutdown_result = @shutdown_mutex.synchronize do
         if @shutdown
-          true
+          until @shutdown_complete
+            # Avoid deadlocking when an in-flight send's on_error callback
+            # re-enters shutdown while the original caller is waiting for it.
+            break if Thread.current == @worker_thread || (@sync_mode && @sync_lock.owned?)
+
+            remaining = deadline && (deadline - monotonic_time)
+            break if remaining && remaining <= 0
+
+            @shutdown_condition.wait(@shutdown_mutex, remaining)
+          end
+          @shutdown_complete ? @shutdown_result : false
         else
           @shutdown = true
-          false
+          nil
         end
       end
-      return if already_shutdown
+      return shutdown_result unless shutdown_result.nil?
 
-      self.class._decrement_instance_count(@api_key) unless @disabled
-      @feature_flags_poller&.shutdown_poller
-      flush
-      if @sync_mode
-        @sync_lock.synchronize { @transport&.shutdown }
-      else
-        @worker&.shutdown
-        @worker_thread&.join(1)
-      end
-      @distinct_id_has_sent_flag_calls_mutex.synchronize do
-        @distinct_id_has_sent_flag_calls.clear
+      flushed = false
+      begin
+        self.class._decrement_instance_count(@api_key) unless @disabled
+        @feature_flags_poller&.shutdown_poller
+        flushed =
+          if @sync_mode
+            # Waiting for @sync_lock lets any in-flight sync send finish before
+            # the connection is closed.
+            @sync_lock.synchronize { @transport&.shutdown }
+            true
+          else
+            drained = flush(timeout: timeout)
+            @worker&.shutdown
+            @worker_thread&.join(1)
+            drained
+          end
+        @distinct_id_has_sent_flag_calls_mutex.synchronize do
+          @distinct_id_has_sent_flag_calls.clear
+        end
+        flushed
+      ensure
+        @shutdown_mutex.synchronize do
+          @shutdown_result = flushed
+          @shutdown_complete = true
+          @shutdown_condition.broadcast
+        end
       end
     end
 

data/lib/posthog/send_worker.rb

@@ -213,9 +213,5 @@ module PostHog
     rescue StandardError => e
       logger.error("Error shutting down transport: #{e.message}")
     end
-
-    def monotonic_time
-      Process.clock_gettime(Process::CLOCK_MONOTONIC)
-    end
   end
 end

data/lib/posthog/utils.rb

@@ -136,6 +136,12 @@ module PostHog
       end
     end
 
+    # public: Current monotonic clock time in seconds, for measuring durations
+    #
+    def monotonic_time
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+
     # Hash that clears itself when it reaches a maximum length.
     #
     # @api private

data/lib/posthog/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module PostHog
-  VERSION = '3.21.0'
+  VERSION = '3.22.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: posthog-ruby
 version: !ruby/object:Gem::Version
-  version: 3.21.0
+  version: 3.22.0
 platform: ruby
 authors:
 - ''