posthog-ruby 3.5.5 → 3.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a707a12f37f1d97a91f179b0b6fa6695b6c6342957de137b38f66ebc0e008a5d
-  data.tar.gz: ecace6615c9121841987baaed7178327e1a50db76f73b5b890f6e42da7c30656
+  metadata.gz: dc278624783a997ea124cc47e7d6724c2160b10509dde00293725e66ca4edceb
+  data.tar.gz: db194b891449029e91c8f20d82b873fe8aebe69182db77053ce966366af94ea9
 SHA512:
-  metadata.gz: 3f584a56131c572124ab4c46b452ca96538b94c386934ee99b768de5dd84c5a34236e65edfefde9bed167fde431b311f70f08fd36786dd586b4173556029b6a2
-  data.tar.gz: ddd803d8420443ea7ee1fb015a46dfad302a11eab98c02ef70a16820e5e8bea73a82bea644bfb6d1109b11e744739be82810ac4bdaf8375cd9cb2847d79df4eb
+  metadata.gz: 294eacce50eef253e5d6890c2c972c300e8caab9462889648f89cb2449a06357343515d54935b69b83ae0707e2c77adc2010bad8efc14f7e393c8427744422b3
+  data.tar.gz: ffa9da1ee5e32b462e83bc3a4f362bf855dd62931d3351dd41850909300c85921cd2e6b56851fd752f165c9a429cb02b28336a69155187451b4326ca65d6798d

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,11 @@ 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+.
+    # @option opts [Object] :flag_definition_cache_provider An object implementing the
+    #   {FlagDefinitionCacheProvider} interface for distributed flag definition caching.
+    #   EXPERIMENTAL: This API may change in future minor version bumps.
     def initialize(opts = {})
       symbolize_keys!(opts)
 
@@ -41,17 +80,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],
@@ -59,7 +123,8 @@ module PostHog
           @api_key,
           opts[:host],
           opts[:feature_flag_request_timeout_seconds] || Defaults::FeatureFlags::FLAG_REQUEST_TIMEOUT_SECONDS,
-          opts[:on_error]
+          opts[:on_error],
+          flag_definition_cache_provider: opts[:flag_definition_cache_provider]
         )
 
       @distinct_id_has_sent_flag_calls = SizeLimitedHash.new(Defaults::MAX_HASH_SIZE) do |hash, key|
@@ -74,6 +139,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 +515,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 +560,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 +595,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

@@ -6,6 +6,7 @@ require 'json'
 require 'posthog/version'
 require 'posthog/logging'
 require 'posthog/feature_flag'
+require 'posthog/flag_definition_cache'
 require 'digest'
 
 module PostHog
@@ -29,7 +30,8 @@ module PostHog
       project_api_key,
       host,
       feature_flag_request_timeout_seconds,
-      on_error = nil
+      on_error = nil,
+      flag_definition_cache_provider: nil
     )
       @polling_interval = polling_interval || 30
       @personal_api_key = personal_api_key
@@ -44,6 +46,10 @@ module PostHog
       @on_error = on_error || proc { |status, error| }
       @quota_limited = Concurrent::AtomicBoolean.new(false)
       @flags_etag = Concurrent::AtomicReference.new(nil)
+
+      @flag_definition_cache_provider = flag_definition_cache_provider
+      FlagDefinitionCacheProvider.validate!(@flag_definition_cache_provider) if @flag_definition_cache_provider
+
       @task =
         Concurrent::TimerTask.new(
           execution_interval: polling_interval
@@ -372,6 +378,13 @@ module PostHog
 
     def shutdown_poller
       @task.shutdown
+      return unless @flag_definition_cache_provider
+
+      begin
+        @flag_definition_cache_provider.shutdown
+      rescue StandardError => e
+        logger.error("[FEATURE FLAGS] Cache provider shutdown error: #{e}")
+      end
     end
 
     # Class methods
@@ -1006,6 +1019,38 @@ module PostHog
     end
 
     def _load_feature_flags
+      should_fetch = true
+
+      if @flag_definition_cache_provider
+        begin
+          should_fetch = @flag_definition_cache_provider.should_fetch_flag_definitions?
+        rescue StandardError => e
+          logger.error("[FEATURE FLAGS] Cache provider should_fetch error: #{e}")
+          should_fetch = true
+        end
+      end
+
+      unless should_fetch
+        begin
+          cached_data = @flag_definition_cache_provider.flag_definitions
+          if cached_data
+            logger.debug '[FEATURE FLAGS] Using cached flag definitions from external cache'
+            _apply_flag_definitions(cached_data)
+            return
+          elsif @feature_flags.empty?
+            # Emergency fallback: cache empty and no flags loaded -> fetch from API
+            should_fetch = true
+          end
+        rescue StandardError => e
+          logger.error("[FEATURE FLAGS] Cache provider get error: #{e}")
+          should_fetch = true
+        end
+      end
+
+      _fetch_and_apply_flag_definitions if should_fetch
+    end
+
+    def _fetch_and_apply_flag_definitions
       begin
         res = _request_feature_flag_definitions(etag: @flags_etag.value)
       rescue StandardError => e
@@ -1040,21 +1085,48 @@ module PostHog
         # Only update ETag on successful responses with flag data
         @flags_etag.value = res[:etag]
 
-        @feature_flags = res[:flags] || []
-        @feature_flags_by_key = {}
-        @feature_flags.each do |flag|
-          @feature_flags_by_key[flag[:key]] = flag unless flag[:key].nil?
-        end
-        @group_type_mapping = res[:group_type_mapping] || {}
-        @cohorts = res[:cohorts] || {}
-
-        logger.debug "Loaded #{@feature_flags.length} feature flags and #{@cohorts.length} cohorts"
-        @loaded_flags_successfully_once.make_true if @loaded_flags_successfully_once.false?
+        _apply_flag_definitions(res)
+        _store_in_cache_provider
       else
         logger.debug "Failed to load feature flags: #{res}"
       end
     end
 
+    def _store_in_cache_provider
+      return unless @flag_definition_cache_provider
+
+      begin
+        data = {
+          flags: @feature_flags.to_a,
+          group_type_mapping: @group_type_mapping.to_h,
+          cohorts: @cohorts.to_h
+        }
+        @flag_definition_cache_provider.on_flag_definitions_received(data)
+      rescue StandardError => e
+        logger.error("[FEATURE FLAGS] Cache provider store error: #{e}")
+      end
+    end
+
+    def _apply_flag_definitions(data)
+      flags = get_by_symbol_or_string_key(data, 'flags') || []
+      group_type_mapping = get_by_symbol_or_string_key(data, 'group_type_mapping') || {}
+      cohorts = get_by_symbol_or_string_key(data, 'cohorts') || {}
+
+      @feature_flags = Concurrent::Array.new(flags.map { |f| deep_symbolize_keys(f) })
+
+      new_by_key = {}
+      @feature_flags.each do |flag|
+        new_by_key[flag[:key]] = flag unless flag[:key].nil?
+      end
+      @feature_flags_by_key = new_by_key
+
+      @group_type_mapping = Concurrent::Hash[deep_symbolize_keys(group_type_mapping)]
+      @cohorts = Concurrent::Hash[deep_symbolize_keys(cohorts)]
+
+      logger.debug "Loaded #{@feature_flags.length} feature flags and #{@cohorts.length} cohorts"
+      @loaded_flags_successfully_once.make_true if @loaded_flags_successfully_once.false?
+    end
+
     def _request_feature_flag_definitions(etag: nil)
       uri = URI("#{@host}/api/feature_flag/local_evaluation")
       uri.query = URI.encode_www_form([['token', @project_api_key], %w[send_cohorts true]])

data/lib/posthog/flag_definition_cache.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module PostHog
+  # Interface for external caching of feature flag definitions.
+  #
+  # EXPERIMENTAL: This API may change in future minor version bumps.
+  #
+  # Enables multi-worker environments (Kubernetes, load-balanced servers,
+  # serverless functions) to share flag definitions via an external cache,
+  # reducing redundant API calls.
+  #
+  # Implement the four required methods on any object and pass it as the
+  # +:flag_definition_cache_provider+ option when creating a {Client}.
+  #
+  # == Required Methods
+  #
+  # [+flag_definitions+]
+  #   Retrieve cached flag definitions. Return a Hash with +:flags+,
+  #   +:group_type_mapping+, and +:cohorts+ keys, or +nil+ if the cache
+  #   is empty. Returning +nil+ triggers an API fetch when no flags are
+  #   loaded yet (emergency fallback).
+  #
+  # [+should_fetch_flag_definitions?+]
+  #   Return +true+ if this instance should fetch new definitions from the
+  #   API, +false+ to read from cache instead. Use for distributed lock
+  #   coordination so only one worker fetches at a time.
+  #
+  # [+on_flag_definitions_received(data)+]
+  #   Called after successfully fetching new definitions from the API.
+  #   +data+ is a Hash with +:flags+, +:group_type_mapping+, and +:cohorts+
+  #   keys (plain Ruby types, not Concurrent:: wrappers). Store it in your
+  #   external cache.
+  #
+  # [+shutdown+]
+  #   Called when the PostHog client shuts down. Release any distributed
+  #   locks and clean up resources.
+  #
+  # == Error Handling
+  #
+  # All methods are wrapped in +begin/rescue+. Errors are logged but never
+  # break flag evaluation:
+  # - +should_fetch_flag_definitions?+ errors default to fetching (fail-safe)
+  # - +flag_definitions+ errors fall back to API fetch
+  # - +on_flag_definitions_received+ errors are logged; flags remain in memory
+  # - +shutdown+ errors are logged; shutdown continues
+  #
+  # == Example
+  #
+  #   cache = RedisFlagCache.new(redis, service_key: 'my-service')
+  #   client = PostHog::Client.new(
+  #     api_key: '<project_api_key>',
+  #     personal_api_key: '<personal_api_key>',
+  #     flag_definition_cache_provider: cache
+  #   )
+  #
+  module FlagDefinitionCacheProvider
+    REQUIRED_METHODS = %i[
+      flag_definitions
+      should_fetch_flag_definitions?
+      on_flag_definitions_received
+      shutdown
+    ].freeze
+
+    # Validates that +provider+ implements all required methods.
+    # Raises +ArgumentError+ listing any missing methods.
+    #
+    # @param provider [Object] the cache provider to validate
+    # @raise [ArgumentError] if any required methods are missing
+    def self.validate!(provider)
+      missing = REQUIRED_METHODS.reject { |m| provider.respond_to?(m) }
+      return if missing.empty?
+
+      raise ArgumentError,
+            "Flag definition cache provider is missing required methods: #{missing.join(', ')}. " \
+            'See PostHog::FlagDefinitionCacheProvider for the required interface.'
+    end
+  end
+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/utils.rb

@@ -27,6 +27,21 @@ module PostHog
       hash.transform_keys(&:to_s)
     end
 
+    # public: Recursively convert all keys to symbols in a Hash/Array tree
+    #
+    def deep_symbolize_keys(obj)
+      case obj
+      when Hash
+        obj.each_with_object({}) do |(key, value), result|
+          result[key.to_sym] = deep_symbolize_keys(value)
+        end
+      when Array
+        obj.map { |item| deep_symbolize_keys(item) }
+      else
+        obj
+      end
+    end
+
     # public: Returns a new hash with all the date values in the into iso8601
     #         strings
     #

data/lib/posthog/version.rb

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

data/lib/posthog.rb

@@ -12,3 +12,4 @@ require 'posthog/logging'
 require 'posthog/exception_capture'
 require 'posthog/feature_flag_error'
 require 'posthog/feature_flag_result'
+require 'posthog/flag_definition_cache'

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: posthog-ruby
 version: !ruby/object:Gem::Version
-  version: 3.5.5
+  version: 3.6.1
 platform: ruby
 authors:
 - ''
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-03-05 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: concurrent-ruby
@@ -45,6 +44,7 @@ files:
 - lib/posthog/feature_flag_result.rb
 - lib/posthog/feature_flags.rb
 - lib/posthog/field_parser.rb
+- lib/posthog/flag_definition_cache.rb
 - lib/posthog/logging.rb
 - lib/posthog/message_batch.rb
 - lib/posthog/noop_worker.rb
@@ -59,7 +59,6 @@ licenses:
 - MIT
 metadata:
   rubygems_mfa_required: 'true'
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -74,8 +73,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.10
-signing_key:
+rubygems_version: 4.0.6
 specification_version: 4
 summary: PostHog library
 test_files: []