posthog-ruby 3.5.4 → 3.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5026e37833cd30bd175b2b59af91cbffbbe23d253fb53db3a1ce47882e5f02b9
-  data.tar.gz: 0ef36c07c207cd1fdd559bba7b831ed31ce19295511b7d7c07a6840d1408ece2
+  metadata.gz: f9cb5856b81b9b86c58818eb7063f4e8ca950fb1e9f9b23d998b16a43c21f9dc
+  data.tar.gz: e0d5f9a42f919ec8924b096f2c0bb3f32a5052f6b09d868ccf194dab6d5f4980
 SHA512:
-  metadata.gz: 349424eaa2f8cfd9d3c038a3e57991982d8fc2a75957a90d70b8cb7591af02acb8c167eb095f4ffe57538e8c86232fe072292945fb2f53d0ecef2639f84c8273
-  data.tar.gz: 3af2539414d839b9fccf948bf1e8574249da3c554e40cacd4067963c7e9e93b1810eec2343d53fddafc330eddfe83c1d07e4e09946a9d6ce285a746e9e9dca2d
+  metadata.gz: b2736eedb29171b83370b7be1eea115d015a907f2c27ed656a4ab8c708050867464a82608b1520e84d2bf045031625ae0645191395bb9992622e24ddc0dbb5e4
+  data.tar.gz: 89f33534310162d51b7edd63f99f87ef41e2b803fad8cbec9930e7c382143ae63297ac273425468b91bfbfbe863a68a06a8659364ca881ba48245a907d97bd2e

data/lib/posthog/client.rb

@@ -8,6 +8,8 @@ require 'posthog/logging'
 require 'posthog/utils'
 require 'posthog/send_worker'
 require 'posthog/noop_worker'
+require 'posthog/message_batch'
+require 'posthog/transport'
 require 'posthog/feature_flags'
 require 'posthog/send_feature_flags_options'
 require 'posthog/exception_capture'
@@ -17,6 +19,35 @@ module PostHog
     include PostHog::Utils
     include PostHog::Logging
 
+    # Thread-safe tracking of client instances per API key for singleton warnings
+    @instances_by_api_key = {}
+    @instances_mutex = Mutex.new
+
+    class << self
+      # Resets instance tracking. Used primarily for testing.
+      # In production, instance counts persist for the lifetime of the process.
+      def reset_instance_tracking!
+        @instances_mutex.synchronize do
+          @instances_by_api_key = {}
+        end
+      end
+
+      def _increment_instance_count(api_key)
+        @instances_mutex.synchronize do
+          count = @instances_by_api_key[api_key] || 0
+          @instances_by_api_key[api_key] = count + 1
+          count
+        end
+      end
+
+      def _decrement_instance_count(api_key)
+        @instances_mutex.synchronize do
+          count = (@instances_by_api_key[api_key] || 1) - 1
+          @instances_by_api_key[api_key] = [count, 0].max
+        end
+      end
+    end
+
     # @param [Hash] opts
     # @option opts [String] :api_key Your project's api_key
     # @option opts [String] :personal_api_key Your personal API key
@@ -24,6 +55,9 @@ module PostHog
     #   remain queued. Defaults to 10_000.
     # @option opts [Bool] :test_mode +true+ if messages should remain
     #   queued for testing. Defaults to +false+.
+    # @option opts [Bool] :sync_mode +true+ to send events synchronously
+    #   on the calling thread. Useful in forking environments like Sidekiq
+    #   and Resque. Defaults to +false+.
     # @option opts [Proc] :on_error Handles error calls from the API.
     # @option opts [String] :host Fully qualified hostname of the PostHog server. Defaults to `https://app.posthog.com`
     # @option opts [Integer] :feature_flags_polling_interval How often to poll for feature flag definition changes.
@@ -32,6 +66,8 @@ module PostHog
     #   Measured in seconds, defaults to 3.
     # @option opts [Proc] :before_send A block that receives the event hash and should return either a modified hash
     #   to be sent to PostHog or nil to prevent the event from being sent. e.g. `before_send: ->(event) { event }`
+    # @option opts [Bool] :disable_singleton_warning +true+ to suppress the warning when multiple clients
+    #   share the same API key. Use only when you intentionally need multiple clients. Defaults to +false+.
     def initialize(opts = {})
       symbolize_keys!(opts)
 
@@ -41,17 +77,42 @@ module PostHog
       @api_key = opts[:api_key]
       @max_queue_size = opts[:max_queue_size] || Defaults::Queue::MAX_SIZE
       @worker_mutex = Mutex.new
+      @sync_mode = opts[:sync_mode] == true && !opts[:test_mode]
+      @on_error = opts[:on_error] || proc { |status, error| }
       @worker = if opts[:test_mode]
                   NoopWorker.new(@queue)
+                elsif @sync_mode
+                  nil
                 else
                   SendWorker.new(@queue, @api_key, opts)
                 end
+      if @sync_mode
+        @transport = Transport.new(
+          api_host: opts[:host],
+          skip_ssl_verification: opts[:skip_ssl_verification],
+          retries: 3
+        )
+        @sync_lock = Mutex.new
+      end
       @worker_thread = nil
       @feature_flags_poller = nil
       @personal_api_key = opts[:personal_api_key]
 
       check_api_key!
 
+      # Warn when multiple clients are created with the same API key (can cause dropped events)
+      unless opts[:test_mode] || opts[:disable_singleton_warning]
+        previous_count = self.class._increment_instance_count(@api_key)
+        if previous_count >= 1
+          logger.warn(
+            'Multiple PostHog client instances detected for the same API key. ' \
+            'This can cause dropped events and inconsistent behavior. ' \
+            'Use a singleton pattern: instantiate once and reuse the client. ' \
+            'See https://posthog.com/docs/libraries/ruby'
+          )
+        end
+      end
+
       @feature_flags_poller =
         FeatureFlagsPoller.new(
           opts[:feature_flags_polling_interval],
@@ -74,6 +135,12 @@ module PostHog
     # Use only for scripts which are not long-running, and will specifically
     # exit
     def flush
+      if @sync_mode
+        # Wait for any in-flight sync send to complete
+        @sync_lock.synchronize {} # rubocop:disable Lint/EmptyBlock
+        return
+      end
+
       while !@queue.empty? || @worker.is_requesting?
         ensure_worker_running
         sleep(0.1)
@@ -444,8 +511,14 @@ module PostHog
     end
 
     def shutdown
+      self.class._decrement_instance_count(@api_key) if @api_key
       @feature_flags_poller.shutdown_poller
       flush
+      if @sync_mode
+        @sync_lock.synchronize { @transport&.shutdown }
+      else
+        @worker&.shutdown
+      end
     end
 
     private
@@ -483,6 +556,11 @@ module PostHog
       # add our request id for tracing purposes
       action[:messageId] ||= uid
 
+      if @sync_mode
+        send_sync(action)
+        return true
+      end
+
       if @queue.length < @max_queue_size
         @queue << action
         ensure_worker_running
@@ -513,6 +591,22 @@ module PostHog
       end
     end
 
+    def send_sync(action)
+      batch = MessageBatch.new(1)
+      begin
+        batch << action
+      rescue MessageBatch::JSONGenerationError => e
+        @on_error.call(-1, e.to_s)
+        return
+      end
+      return if batch.empty?
+
+      @sync_lock.synchronize do
+        res = @transport.send(@api_key, batch)
+        @on_error.call(res.status, res.error) unless res.status == 200
+      end
+    end
+
     def worker_running?
       @worker_thread&.alive?
     end

data/lib/posthog/feature_flags.rb

@@ -422,6 +422,103 @@ module PostHog
       parsed_dt
     end
 
+    # Parse a semver string into a comparable [major, minor, patch] integer array.
+    # Handles v-prefix, whitespace, pre-release suffixes. Defaults missing components to 0.
+    def self.parse_semver(value)
+      raise InconclusiveMatchError, 'Invalid semver format' if value.nil?
+
+      text = value.to_s.strip.sub(/^[vV]/, '')
+
+      raise InconclusiveMatchError, 'Invalid semver format' if text.empty?
+
+      # Strip pre-release and build metadata suffixes
+      text = text.split('-')[0].split('+')[0]
+      parts = text.split('.')
+
+      raise InconclusiveMatchError, 'Invalid semver format' if parts.empty? || parts[0].to_s.empty?
+
+      # Check for leading dot or non-numeric parts
+      parts.each do |part|
+        raise InconclusiveMatchError, 'Invalid semver format' if part.empty? || part !~ /^\d+$/
+      end
+
+      major = parts[0].to_i
+      minor = parts.length > 1 ? parts[1].to_i : 0
+      patch = parts.length > 2 ? parts[2].to_i : 0
+
+      [major, minor, patch]
+    end
+
+    # Returns bounds for tilde (~) range:
+    # ~X       → >=X.0.0 <(X+1).0.0
+    # ~X.Y     → >=X.Y.0 <X.(Y+1).0
+    # ~X.Y.Z   → >=X.Y.Z <X.(Y+1).0
+    def self.semver_tilde_bounds(value)
+      major, minor, patch = parse_semver(value)
+      lower = [major, minor, patch]
+
+      # Determine how many components were provided
+      text = value.to_s.strip.sub(/^[vV]/, '')
+      text = text.split('-')[0].split('+')[0]
+      component_count = text.split('.').length
+
+      upper = if component_count == 1
+                # Major-only: bump major
+                [major + 1, 0, 0]
+              else
+                # Major.minor or major.minor.patch: bump minor
+                [major, minor + 1, 0]
+              end
+
+      [lower, upper]
+    end
+
+    # Returns bounds for caret (^) range per semver spec:
+    # ^X.Y.Z where X > 0 → >=X.Y.Z <(X+1).0.0
+    # ^0.Y.Z where Y > 0 → >=0.Y.Z <0.(Y+1).0
+    # ^0.0.Z → >=0.0.Z <0.0.(Z+1)
+    def self.semver_caret_bounds(value)
+      major, minor, patch = parse_semver(value)
+      lower = [major, minor, patch]
+
+      upper = if major.positive?
+                [major + 1, 0, 0]
+              elsif minor.positive?
+                [0, minor + 1, 0]
+              else
+                [0, 0, patch + 1]
+              end
+
+      [lower, upper]
+    end
+
+    # Returns bounds for wildcard (*) range:
+    # X.* or X → >=X.0.0 <(X+1).0.0
+    # X.Y.* → >=X.Y.0 <X.(Y+1).0
+    def self.semver_wildcard_bounds(value)
+      cleaned = value.to_s.strip.sub(/^[vV]/, '').gsub('*', '').chomp('.')
+      parts = cleaned.split('.').reject(&:empty?)
+
+      raise InconclusiveMatchError, 'Invalid semver wildcard format' if parts.empty?
+
+      parts.each do |part|
+        raise InconclusiveMatchError, 'Invalid semver wildcard format' if part !~ /^\d+$/
+      end
+
+      major = parts[0].to_i
+      case parts.length
+      when 1
+        [[major, 0, 0], [major + 1, 0, 0]]
+      when 2
+        minor = parts[1].to_i
+        [[major, minor, 0], [major, minor + 1, 0]]
+      else
+        minor = parts[1].to_i
+        patch = parts[2].to_i
+        [[major, minor, patch], [major, minor, patch + 1]]
+      end
+    end
+
     def self.match_property(property, property_values, cohort_properties = {})
       # only looks for matches where key exists in property_values
       # doesn't support operator is_not_set
@@ -496,6 +593,36 @@ module PostHog
         elsif operator == 'is_date_after'
           override_date > parsed_date
         end
+      when 'semver_eq', 'semver_neq', 'semver_gt', 'semver_gte', 'semver_lt', 'semver_lte'
+        override_parsed = parse_semver(override_value)
+        flag_parsed = parse_semver(value)
+
+        case operator
+        when 'semver_eq'
+          override_parsed == flag_parsed
+        when 'semver_neq'
+          override_parsed != flag_parsed
+        when 'semver_gt'
+          (override_parsed <=> flag_parsed) == 1
+        when 'semver_gte'
+          (override_parsed <=> flag_parsed) >= 0
+        when 'semver_lt'
+          (override_parsed <=> flag_parsed) == -1
+        when 'semver_lte'
+          (override_parsed <=> flag_parsed) <= 0
+        end
+      when 'semver_tilde'
+        override_parsed = parse_semver(override_value)
+        lower, upper = semver_tilde_bounds(value)
+        (override_parsed <=> lower) >= 0 && (override_parsed <=> upper) == -1
+      when 'semver_caret'
+        override_parsed = parse_semver(override_value)
+        lower, upper = semver_caret_bounds(value)
+        (override_parsed <=> lower) >= 0 && (override_parsed <=> upper) == -1
+      when 'semver_wildcard'
+        override_parsed = parse_semver(override_value)
+        lower, upper = semver_wildcard_bounds(value)
+        (override_parsed <=> lower) >= 0 && (override_parsed <=> upper) == -1
       else
         raise InconclusiveMatchError, "Unknown operator: #{operator}"
       end

data/lib/posthog/noop_worker.rb

@@ -15,5 +15,9 @@ module PostHog
     def is_requesting? # rubocop:disable Naming/PredicateName
       false
     end
+
+    def shutdown
+      # Does nothing
+    end
   end
 end

data/lib/posthog/send_worker.rb

@@ -54,6 +54,10 @@ module PostHog
       @transport.shutdown
     end
 
+    def shutdown
+      @transport.shutdown
+    end
+
     # public: Check whether we have outstanding requests.
     #
     # TODO: Rename to `requesting?` in future version

data/lib/posthog/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: posthog-ruby
 version: !ruby/object:Gem::Version
-  version: 3.5.4
+  version: 3.6.0
 platform: ruby
 authors:
 - ''
@@ -72,7 +72,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.3
+rubygems_version: 4.0.6
 specification_version: 4
 summary: PostHog library
 test_files: []