posthog-ruby 3.18.0 → 3.20.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 75e17034bb60a9af9539cfe28137a91a71d83305e4d3dc7d1db3844870efac38
-  data.tar.gz: b511f71723032dff61fc998ae145d1e650eb6d90bdb4df84024e9335613aed71
+  metadata.gz: 36dffe9438cc269541f1642261b27b020bf05993eda1ad9999887428caa1667b
+  data.tar.gz: 9575ff454af5b89c0be1eb6abf4c7a1158fdbca88d4c708860339a1710b1393d
 SHA512:
-  metadata.gz: d27932884831bba0abb8b90315c1c8c684ae821aa85a5f6df8b486339d53097022ee2d58303b913a46cb05cf576230bf1f45b2ffdbdf465c79fce4875239cfb9
-  data.tar.gz: 043c0f02fb14f744898e7910623757931021d03cb0fbcacc46a305ec2f4d753df81a1ed8482b72f6e9c7e8bc1c826c78b86e889491ceb4c112dfa1844b1cf82a
+  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
 
@@ -609,7 +617,8 @@ module PostHog
           id: definition[:id],
           version: nil,
           reason: FeatureFlagEvaluations::EVALUATED_LOCALLY_REASON,
-          locally_evaluated: true
+          locally_evaluated: true,
+          has_experiment: definition[:has_experiment]
         )
         locally_evaluated_keys << key.to_s
       end
@@ -649,7 +658,8 @@ module PostHog
               id: metadata ? metadata.id : nil,
               version: metadata ? metadata.version : nil,
               reason: reason ? (reason.description || reason.code) : nil,
-              locally_evaluated: false
+              locally_evaluated: false,
+              has_experiment: metadata&.has_experiment
             )
           end
         rescue StandardError => e
@@ -766,10 +776,12 @@ module PostHog
       # Remove internal information
       response.delete(:requestId)
       response.delete(:evaluatedAt)
+      response.delete(:flagDetails)
       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
@@ -784,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.
     #
@@ -921,7 +944,8 @@ module PostHog
       person_properties, group_properties = add_local_person_and_group_properties(
         groups, person_properties, group_properties
       )
-      feature_flag_response, flag_was_locally_evaluated, request_id, evaluated_at, feature_flag_error, payload =
+      feature_flag_response, flag_was_locally_evaluated, request_id, evaluated_at, feature_flag_error, payload,
+        has_experiment =
         @feature_flags_poller.get_feature_flag(
           key, distinct_id, groups, person_properties, group_properties, only_evaluate_locally
         )
@@ -931,6 +955,7 @@ module PostHog
           '$feature_flag_response' => feature_flag_response,
           'locally_evaluated' => flag_was_locally_evaluated
         }
+        properties['$feature_flag_has_experiment'] = has_experiment unless has_experiment.nil?
         properties['$feature_flag_request_id'] = request_id if request_id
         properties['$feature_flag_evaluated_at'] = evaluated_at if evaluated_at
         properties['$feature_flag_error'] = feature_flag_error if feature_flag_error

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_flag.rb

@@ -68,7 +68,7 @@ module PostHog
   #
   # @api private
   class FeatureFlagMetadata
-    attr_reader :id, :version, :payload, :description
+    attr_reader :id, :version, :payload, :description, :has_experiment
 
     # @param json [Hash] Raw metadata returned by /flags.
     def initialize(json)
@@ -77,6 +77,9 @@ module PostHog
       @version = json['version']
       @payload = json['payload']
       @description = json['description']
+      # Whether the flag is linked to an experiment. nil when the server
+      # (an older deployment) does not report the field.
+      @has_experiment = json['has_experiment']
     end
   end
 end

data/lib/posthog/feature_flag_evaluations.rb

@@ -13,7 +13,7 @@ module PostHog
     EVALUATED_LOCALLY_REASON = 'Evaluated locally'
 
     EvaluatedFlagRecord = Struct.new(
-      :key, :enabled, :variant, :payload, :id, :version, :reason, :locally_evaluated,
+      :key, :enabled, :variant, :payload, :id, :version, :reason, :locally_evaluated, :has_experiment,
       keyword_init: true
     )
 
@@ -169,6 +169,7 @@ module PostHog
       }
 
       if flag
+        properties['$feature_flag_has_experiment'] = flag.has_experiment unless flag.has_experiment.nil?
         properties['$feature_flag_payload'] = flag.payload unless flag.payload.nil?
         properties['$feature_flag_id'] = flag.id if flag.id
         properties['$feature_flag_version'] = flag.version if flag.version

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,
@@ -221,6 +240,11 @@ module PostHog
       end
 
       flag_was_locally_evaluated = !response.nil?
+      # Whether the flag is linked to an experiment, as reported by the server.
+      # Locally-evaluated flags carry it in the stored definition; remotely
+      # evaluated flags carry it in the response metadata. nil when the server
+      # (an older deployment) does not report it.
+      has_experiment = feature_flag[:has_experiment] if flag_was_locally_evaluated
 
       request_id = nil
       evaluated_at = nil
@@ -253,6 +277,9 @@ module PostHog
           payload = payloads[key]
           feature_flag_error = errors.join(',') unless errors.empty?
 
+          flag_detail = flags_data[:flagDetails]&.[](key.to_sym)
+          has_experiment = flag_detail&.metadata&.has_experiment
+
           logger.debug "Successfully computed flag remotely: #{key} -> #{response}"
         rescue Timeout::Error => e
           @on_error.call(-1, "Timeout while fetching flags remotely: #{e}")
@@ -266,7 +293,7 @@ module PostHog
         end
       end
 
-      [response, flag_was_locally_evaluated, request_id, evaluated_at, feature_flag_error, payload]
+      [response, flag_was_locally_evaluated, request_id, evaluated_at, feature_flag_error, payload, has_experiment]
     end
 
     def get_all_flags(
@@ -324,10 +351,12 @@ module PostHog
       errors_while_computing = false
       quota_limited = nil
       status_code = nil
+      flag_details = nil
 
       if fallback_to_server && !only_evaluate_locally
         begin
           flags_and_payloads = get_flags(distinct_id, groups, person_properties, group_properties)
+          flag_details = flags_and_payloads[:flags]
           errors_while_computing = flags_and_payloads[:errorsWhileComputingFlags] || false
           quota_limited = flags_and_payloads[:quotaLimited]
           status_code = flags_and_payloads[:status]
@@ -368,6 +397,7 @@ module PostHog
       {
         featureFlags: flags,
         featureFlagPayloads: payloads,
+        flagDetails: flag_details,
         requestId: request_id,
         evaluatedAt: evaluated_at,
         errorsWhileComputingFlags: errors_while_computing,
@@ -1172,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
@@ -1220,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.18.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.18.0
+  version: 3.20.0
 platform: ruby
 authors:
 - ''