posthog-ruby 3.6.0 → 3.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f9cb5856b81b9b86c58818eb7063f4e8ca950fb1e9f9b23d998b16a43c21f9dc
-  data.tar.gz: e0d5f9a42f919ec8924b096f2c0bb3f32a5052f6b09d868ccf194dab6d5f4980
+  metadata.gz: dc278624783a997ea124cc47e7d6724c2160b10509dde00293725e66ca4edceb
+  data.tar.gz: db194b891449029e91c8f20d82b873fe8aebe69182db77053ce966366af94ea9
 SHA512:
-  metadata.gz: b2736eedb29171b83370b7be1eea115d015a907f2c27ed656a4ab8c708050867464a82608b1520e84d2bf045031625ae0645191395bb9992622e24ddc0dbb5e4
-  data.tar.gz: 89f33534310162d51b7edd63f99f87ef41e2b803fad8cbec9930e7c382143ae63297ac273425468b91bfbfbe863a68a06a8659364ca881ba48245a907d97bd2e
+  metadata.gz: 294eacce50eef253e5d6890c2c972c300e8caab9462889648f89cb2449a06357343515d54935b69b83ae0707e2c77adc2010bad8efc14f7e393c8427744422b3
+  data.tar.gz: ffa9da1ee5e32b462e83bc3a4f362bf855dd62931d3351dd41850909300c85921cd2e6b56851fd752f165c9a429cb02b28336a69155187451b4326ca65d6798d

data/lib/posthog/client.rb

@@ -68,6 +68,9 @@ module PostHog
     #   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)
 
@@ -120,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|

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/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.6.0'
+  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,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: posthog-ruby
 version: !ruby/object:Gem::Version
-  version: 3.6.0
+  version: 3.6.1
 platform: ruby
 authors:
 - ''
@@ -44,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