posthog-ruby 3.19.0 → 3.20.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b23e0da0723e7582825d0888d8c6ffd9b3ad0a77e5eec513a40ab3de1faaa306
-  data.tar.gz: 1fc203c912147dc865cb342213ef8ccd3604e4d84f0b0005932c559aa30c8017
+  metadata.gz: 36dffe9438cc269541f1642261b27b020bf05993eda1ad9999887428caa1667b
+  data.tar.gz: 9575ff454af5b89c0be1eb6abf4c7a1158fdbca88d4c708860339a1710b1393d
 SHA512:
-  metadata.gz: 8409ba6d5fb0801643cbd6556a1dabf41441ff522b85d612601ac8547482c5eb139ac68f21250f2f240654f08c03b3ca6cdc0409f57f1c6af9cdd880c677805f
-  data.tar.gz: c7a146c293985480777e6f5139588ca0d897170b8fe15412e9d60561711cb57bec53e70225b8b209916a50835f249b9816bece364be754a56e6f1118454feb52
+  metadata.gz: 9badf7f03c2009d4c643b6e41f4ede382c0bf488eb0ae4d5cf33ec454110102e3fc342b5f3357b58b881f2a513628ba6056f0ccfa82d54ac8cafb4d814ae3811
+  data.tar.gz: e7918e45f9645da0052d65d205359e8384709f645f0f1b5201500a5cc97bb092aed771cd7fac7846f5bfc142fcb9e8168f55d9cbc750c6bbb8aab26e60e1138d

data/lib/posthog/client.rb

@@ -76,6 +76,13 @@ module PostHog
     # @option opts [Integer] :feature_flag_request_max_retries How many times to retry a flag request after a
     #   transient network error. Each retry sleeps on the calling thread before retrying, so this adds to
     #   worst-case latency. Defaults to 1. Set to 0 to disable retrying.
+    # @option opts [Boolean] :feature_flags_async_load +true+ to fetch feature flag definitions for local
+    #   evaluation only on the poller's background thread instead of the calling thread. The constructor
+    #   returns without waiting for definitions: the poller fetches immediately on boot and, if that fails,
+    #   keeps retrying on its regular polling interval until a load succeeds. Until then local evaluation
+    #   treats definitions as absent (check {#feature_flags_loaded?}), so evaluations return nil with
+    #   +only_evaluate_locally: true+, or fall back to the remote flags endpoint (which still runs on the
+    #   calling thread) without it. Defaults to +false+.
     # @option opts [Proc] :before_send A callback 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 [Boolean] :disable_singleton_warning +true+ to suppress the warning when multiple clients share
@@ -162,7 +169,8 @@ module PostHog
             opts[:feature_flag_request_timeout_seconds] || Defaults::FeatureFlags::FLAG_REQUEST_TIMEOUT_SECONDS,
             opts[:on_error],
             flag_definition_cache_provider: opts[:flag_definition_cache_provider],
-            feature_flag_request_max_retries: opts[:feature_flag_request_max_retries]
+            feature_flag_request_max_retries: opts[:feature_flag_request_max_retries],
+            async_load: opts[:feature_flags_async_load] == true
           )
       end
 
@@ -772,7 +780,8 @@ module PostHog
       response
     end
 
-    # Reload locally cached feature flag definitions.
+    # Reload locally cached feature flag definitions synchronously on the
+    # calling thread.
     #
     # @return [void]
     def reload_feature_flags
@@ -787,6 +796,17 @@ module PostHog
       @feature_flags_poller.load_feature_flags(true)
     end
 
+    # Whether feature flag definitions for local evaluation are currently loaded.
+    # False until the first successful load, and false again if a quota-limited
+    # (402) response discards the definitions.
+    #
+    # @return [Boolean]
+    def feature_flags_loaded?
+      return false if @disabled
+
+      @feature_flags_poller.definitions_loaded?
+    end
+
     # Whether the client will actually send events. It is disabled when the
     # api_key is missing or blank, in which case every capture call no-ops.
     #

data/lib/posthog/defaults.rb

@@ -19,6 +19,7 @@ module PostHog
 
     module FeatureFlags
       FLAG_REQUEST_TIMEOUT_SECONDS = 3
+      POLLING_INTERVAL_SECONDS = 30
       # Number of retries for a flag request after a transient network error.
       # Flag requests are stateless and cause no server-side mutation, so
       # retrying is safe.

data/lib/posthog/feature_flags.rb

@@ -30,6 +30,7 @@ module PostHog
     include PostHog::Utils
 
     # @param polling_interval [Integer, nil] Seconds between local feature flag definition polls.
+    #   Defaults to {Defaults::FeatureFlags::POLLING_INTERVAL_SECONDS}.
     # @param secret_key [String, nil] Credential used to fetch local evaluation definitions. Accepts either a
     #   Personal API Key (`phx_...`) or a Project Secret API Key (`phs_...`).
     # @param project_api_key [String] Project API key.
@@ -40,6 +41,9 @@ module PostHog
     # @param feature_flag_request_max_retries [Integer, nil] Retries after a transient network error or retryable
     #   HTTP response status on a flag request. Defaults to {Defaults::FeatureFlags::FLAG_REQUEST_MAX_RETRIES}.
     #   Set to 0 to disable retrying.
+    # @param async_load [Boolean] When true, flag definitions are fetched only on the poller thread: an
+    #   immediate first tick at construction, then the regular polling cadence, which keeps retrying until a
+    #   load succeeds.
     def initialize(
       polling_interval,
       secret_key,
@@ -48,9 +52,10 @@ module PostHog
       feature_flag_request_timeout_seconds,
       on_error = nil,
       flag_definition_cache_provider: nil,
-      feature_flag_request_max_retries: nil
+      feature_flag_request_max_retries: nil,
+      async_load: false
     )
-      @polling_interval = polling_interval || 30
+      @polling_interval = polling_interval || Defaults::FeatureFlags::POLLING_INTERVAL_SECONDS
       @secret_key = secret_key
       @project_api_key = project_api_key
       @host = host
@@ -65,14 +70,16 @@ module PostHog
       @on_error = on_error || proc { |status, error| }
       @quota_limited = Concurrent::AtomicBoolean.new(false)
       @flags_etag = Concurrent::AtomicReference.new(nil)
-      @flag_definitions_loaded_at = nil
+      @flag_definitions_loaded_at = Concurrent::AtomicReference.new(nil)
+      @async_load = async_load
 
       @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
+          execution_interval: @polling_interval,
+          run_now: @async_load
         ) { _load_feature_flags }
 
       # If no secret_key, disable local evaluation & thus polling for definitions
@@ -80,19 +87,31 @@ module PostHog
         logger.info 'No secret_key provided, disabling local evaluation'
         @loaded_flags_successfully_once.make_true
       else
-        # load once before timer
-        load_feature_flags
+        # load once synchronously before timer, unless @async_load
+        load_feature_flags unless @async_load
         @task.execute
       end
     end
 
     def load_feature_flags(force_reload = false)
-      return unless @loaded_flags_successfully_once.false? || force_reload
+      return if (@loaded_flags_successfully_once.true? || @async_load) && !force_reload
 
       _load_feature_flags
     end
 
-    attr_reader :flag_definitions_loaded_at, :feature_flags_by_key
+    # Whether flag definitions are currently loaded. False until the first
+    # successful load, and false again if a quota-limited (402) response
+    # discards them.
+    def definitions_loaded?
+      !@flag_definitions_loaded_at.value.nil?
+    end
+
+    # Epoch milliseconds of the last successful definitions load, or nil.
+    def flag_definitions_loaded_at
+      @flag_definitions_loaded_at.value
+    end
+
+    attr_reader :feature_flags_by_key
 
     def get_feature_variants(
       distinct_id,
@@ -1183,6 +1202,7 @@ module PostHog
         @feature_flags_by_key = {}
         @group_type_mapping = Concurrent::Hash.new
         @cohorts = Concurrent::Hash.new
+        @flag_definitions_loaded_at.value = nil
         @loaded_flags_successfully_once.make_false
         @quota_limited.make_true
         return
@@ -1231,7 +1251,7 @@ module PostHog
       @cohorts = Concurrent::Hash[deep_symbolize_keys(cohorts)]
 
       logger.debug "Loaded #{@feature_flags.length} feature flags and #{@cohorts.length} cohorts"
-      @flag_definitions_loaded_at = (Time.now.to_f * 1000).to_i
+      @flag_definitions_loaded_at.value = (Time.now.to_f * 1000).to_i
       @loaded_flags_successfully_once.make_true if @loaded_flags_successfully_once.false?
     end
 

data/lib/posthog/version.rb

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

metadata

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