posthog-ruby 3.19.0 → 3.21.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b23e0da0723e7582825d0888d8c6ffd9b3ad0a77e5eec513a40ab3de1faaa306
-  data.tar.gz: 1fc203c912147dc865cb342213ef8ccd3604e4d84f0b0005932c559aa30c8017
+  metadata.gz: 4ae3a78450df91e2e4cb88cd69a58e167cdb291dcc02f8ab446e3b0975c270eb
+  data.tar.gz: b912b023ed02a37004cfbe22511437ee4df2a5ec63799d6d47e6f6aa9fc4f164
 SHA512:
-  metadata.gz: 8409ba6d5fb0801643cbd6556a1dabf41441ff522b85d612601ac8547482c5eb139ac68f21250f2f240654f08c03b3ca6cdc0409f57f1c6af9cdd880c677805f
-  data.tar.gz: c7a146c293985480777e6f5139588ca0d897170b8fe15412e9d60561711cb57bec53e70225b8b209916a50835f249b9816bece364be754a56e6f1118454feb52
+  metadata.gz: 42b8b2587ee825e9a5446def45d11940b52a3a2203828b4506b2a4e1c28e2deefd61406df6ab33800bf1055c1475130554d6edef55a1498b478c43a30591f7b0
+  data.tar.gz: 4eec6bdd11abbeee85720d2a68872ad366f39b5c9c28ce72fd96aaf54f3098218578ccac954e35fe01099975d6f5a2afcfe5016b4460520a6341e465f026ed99

data/lib/posthog/client.rb

@@ -22,6 +22,31 @@ module PostHog
     include PostHog::Utils
     include PostHog::Logging
 
+    # Strict allowlist of properties kept on minimal `$feature_flag_called`
+    # events (server-gated, non-experiment flags only). Everything else —
+    # context properties, `$feature/<key>`, payloads, system metadata — is
+    # stripped. Includes symbol forms so allowlisted properties supplied
+    # through context with symbol keys survive.
+    MINIMAL_FLAG_CALLED_EVENT_PROPERTIES = %w[
+      $feature_flag
+      $feature_flag_response
+      $feature_flag_has_experiment
+      $feature_flag_id
+      $feature_flag_version
+      $feature_flag_reason
+      $feature_flag_request_id
+      $feature_flag_evaluated_at
+      $feature_flag_error
+      locally_evaluated
+      $groups
+      $process_person_profile
+      $session_id
+      $is_server
+      $lib
+      $lib_version
+    ].flat_map { |key| [key, key.to_sym] }.freeze
+    private_constant :MINIMAL_FLAG_CALLED_EVENT_PROPERTIES
+
     # Thread-safe tracking of client instances per API key for singleton warnings
     @instances_by_api_key = {}
     @instances_mutex = Mutex.new
@@ -76,6 +101,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 +194,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
 
@@ -245,6 +278,7 @@ module PostHog
       return false if @disabled
 
       symbolize_keys! attrs
+      minimal_flag_called_event = attrs.delete(:_minimal_flag_called_event) == true
       enrich_capture_attrs_with_context(attrs)
 
       # Precedence: an explicit `flags` snapshot always wins, regardless of
@@ -313,7 +347,13 @@ module PostHog
       end
 
       attrs[:is_server] = @is_server
-      enqueue(FieldParser.parse_for_capture(attrs))
+      message = FieldParser.parse_for_capture(attrs)
+      # Minimal events are built from the allowlist after full assembly so
+      # context properties and parser-added metadata can never leak in.
+      if minimal_flag_called_event
+        message[:properties] = message[:properties].slice(*MINIMAL_FLAG_CALLED_EVENT_PROPERTIES)
+      end
+      enqueue(message)
     end
 
     # Captures an exception as an event
@@ -619,6 +659,11 @@ module PostHog
       evaluated_at = nil
       errors_while_computing = false
       quota_limited = false
+      # Server-controlled gate for minimal `$feature_flag_called` events. When
+      # the snapshot uses a remote /flags response, the response's top-level
+      # `minimalFlagCalledEvents` field governs; a local-only snapshot reads
+      # the gate polled with the flag definitions.
+      minimal_flag_called_events = @feature_flags_poller.minimal_flag_called_events
 
       # Skip the remote `/flags` round-trip when the caller scoped the request
       # to a fixed set of `flag_keys` and we've already resolved every one of
@@ -627,10 +672,16 @@ module PostHog
       all_requested_flags_resolved_locally = flag_keys_set && (flag_keys_set - locally_evaluated_keys).empty?
 
       if !only_evaluate_locally && !all_requested_flags_resolved_locally
+        # The gate is team-level, so the /flags response gate supersedes the
+        # poller gate for mixed snapshots — both signals come from the same
+        # server and agree in steady state. When the response omits the gate,
+        # the whole snapshot fails safe to full events.
+        minimal_flag_called_events = false
         begin
           flags_response = @feature_flags_poller.get_flags(
             distinct_id, groups, person_properties, group_properties, flag_keys, disable_geoip
           )
+          minimal_flag_called_events = flags_response[:minimalFlagCalledEvents] == true
           request_id = flags_response[:requestId]
           evaluated_at = flags_response[:evaluatedAt]
           errors_while_computing = flags_response[:errorsWhileComputingFlags] == true
@@ -669,7 +720,8 @@ module PostHog
         evaluated_at: evaluated_at,
         flag_definitions_loaded_at: @feature_flags_poller.flag_definitions_loaded_at,
         errors_while_computing: errors_while_computing,
-        quota_limited: quota_limited
+        quota_limited: quota_limited,
+        minimal_flag_called_events: minimal_flag_called_events
       )
     end
 
@@ -769,10 +821,12 @@ module PostHog
       response.delete(:requestId)
       response.delete(:evaluatedAt)
       response.delete(:flagDetails)
+      response.delete(:minimalFlagCalledEvents)
       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 +841,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.
     #
@@ -865,7 +930,7 @@ module PostHog
     # separate event for each group a user is evaluated under.
     def _capture_feature_flag_called_if_needed(
       distinct_id: nil, key: nil, response: nil, properties: nil,
-      groups: nil, disable_geoip: nil
+      groups: nil, disable_geoip: nil, minimal: false
     )
       response_repr = response.nil? ? '::null::' : response
       groups_repr =
@@ -895,6 +960,7 @@ module PostHog
       }
       msg[:groups] = groups if groups
       msg[:disable_geoip] = disable_geoip unless disable_geoip.nil?
+      msg[:_minimal_flag_called_event] = true if minimal
 
       capture(msg)
     end
@@ -925,7 +991,7 @@ module PostHog
         groups, person_properties, group_properties
       )
       feature_flag_response, flag_was_locally_evaluated, request_id, evaluated_at, feature_flag_error, payload,
-        has_experiment =
+        has_experiment, minimal_flag_called_events =
         @feature_flags_poller.get_feature_flag(
           key, distinct_id, groups, person_properties, group_properties, only_evaluate_locally
         )
@@ -940,9 +1006,13 @@ module PostHog
         properties['$feature_flag_evaluated_at'] = evaluated_at if evaluated_at
         properties['$feature_flag_error'] = feature_flag_error if feature_flag_error
 
+        # Emit a minimal event only when the server gate is on and the flag is
+        # known to have no linked experiment. Any missing signal fails safe to
+        # the full event.
+        minimal = minimal_flag_called_events == true && has_experiment == false
         _capture_feature_flag_called_if_needed(
           distinct_id: distinct_id, key: key, response: feature_flag_response,
-          properties: properties, groups: groups
+          properties: properties, groups: groups, minimal: minimal
         )
       end
 

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

@@ -44,6 +44,8 @@ module PostHog
     # @param flag_definitions_loaded_at [Time, nil] When local flag definitions were loaded.
     # @param errors_while_computing [Boolean] Whether the server reported errors while computing flags.
     # @param quota_limited [Boolean] Whether feature flag evaluation was quota limited.
+    # @param minimal_flag_called_events [Boolean] Server-controlled gate for minimal
+    #   `$feature_flag_called` events.
     # @param accessed [Array<String>, Set<String>, nil] Flag keys already accessed by this snapshot.
     def initialize(
       host: nil,
@@ -56,6 +58,7 @@ module PostHog
       flag_definitions_loaded_at: nil,
       errors_while_computing: false,
       quota_limited: false,
+      minimal_flag_called_events: false,
       accessed: nil
     )
       @host = host
@@ -68,6 +71,7 @@ module PostHog
       @flag_definitions_loaded_at = flag_definitions_loaded_at
       @errors_while_computing = errors_while_computing
       @quota_limited = quota_limited
+      @minimal_flag_called_events = minimal_flag_called_events == true
       @accessed = Set.new(accessed || [])
     end
 
@@ -188,13 +192,19 @@ module PostHog
       errors << 'flag_missing' if flag.nil?
       properties['$feature_flag_error'] = errors.join(',') unless errors.empty?
 
+      # Emit a minimal event only when the server gate is on and the flag is
+      # known to have no linked experiment. Any missing signal (unknown flag,
+      # has_experiment absent) fails safe to the full event.
+      minimal = @minimal_flag_called_events && !flag.nil? && flag.has_experiment == false
+
       @host.capture_flag_called_event_if_needed.call(
         distinct_id: @distinct_id,
         key: key,
         response: response,
         properties: properties,
         groups: @groups,
-        disable_geoip: @disable_geoip
+        disable_geoip: @disable_geoip,
+        minimal: minimal
       )
     end
 
@@ -210,6 +220,7 @@ module PostHog
         flag_definitions_loaded_at: @flag_definitions_loaded_at,
         errors_while_computing: @errors_while_computing,
         quota_limited: @quota_limited,
+        minimal_flag_called_events: @minimal_flag_called_events,
         accessed: @accessed.dup
       )
     end

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,19 @@ 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
+      # Server-controlled gate for minimal `$feature_flag_called` events, read
+      # from the top-level `minimal_flag_called_events` key of the local
+      # evaluation definitions payload. false when the server does not send it.
+      @minimal_flag_called_events = false
       @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 +90,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, :minimal_flag_called_events
 
     def get_feature_variants(
       distinct_id,
@@ -226,6 +248,11 @@ module PostHog
       # 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
+      # Server-controlled gate for minimal `$feature_flag_called` events.
+      # Locally-evaluated flags read it from the definitions payload; remotely
+      # evaluated flags read it from the /flags response. nil when the signal
+      # is unavailable, which fails safe to the full event.
+      minimal_flag_called_events = @minimal_flag_called_events if flag_was_locally_evaluated
 
       request_id = nil
       evaluated_at = nil
@@ -260,6 +287,7 @@ module PostHog
 
           flag_detail = flags_data[:flagDetails]&.[](key.to_sym)
           has_experiment = flag_detail&.metadata&.has_experiment
+          minimal_flag_called_events = flags_data[:minimalFlagCalledEvents]
 
           logger.debug "Successfully computed flag remotely: #{key} -> #{response}"
         rescue Timeout::Error => e
@@ -274,7 +302,8 @@ module PostHog
         end
       end
 
-      [response, flag_was_locally_evaluated, request_id, evaluated_at, feature_flag_error, payload, has_experiment]
+      [response, flag_was_locally_evaluated, request_id, evaluated_at, feature_flag_error, payload, has_experiment,
+       minimal_flag_called_events]
     end
 
     def get_all_flags(
@@ -333,6 +362,7 @@ module PostHog
       quota_limited = nil
       status_code = nil
       flag_details = nil
+      minimal_flag_called_events = nil
 
       if fallback_to_server && !only_evaluate_locally
         begin
@@ -348,6 +378,7 @@ module PostHog
 
           request_id = flags_and_payloads[:requestId]
           evaluated_at = flags_and_payloads[:evaluatedAt]
+          minimal_flag_called_events = flags_and_payloads[:minimalFlagCalledEvents]
 
           # Check if feature_flags are quota limited
           if quota_limited&.include?('feature_flags')
@@ -383,7 +414,8 @@ module PostHog
         evaluatedAt: evaluated_at,
         errorsWhileComputingFlags: errors_while_computing,
         quotaLimited: quota_limited,
-        status: status_code
+        status: status_code,
+        minimalFlagCalledEvents: minimal_flag_called_events
       }
     end
 
@@ -1183,6 +1215,8 @@ module PostHog
         @feature_flags_by_key = {}
         @group_type_mapping = Concurrent::Hash.new
         @cohorts = Concurrent::Hash.new
+        @flag_definitions_loaded_at.value = nil
+        @minimal_flag_called_events = false
         @loaded_flags_successfully_once.make_false
         @quota_limited.make_true
         return
@@ -1206,7 +1240,8 @@ module PostHog
         data = {
           flags: @feature_flags.to_a,
           group_type_mapping: @group_type_mapping.to_h,
-          cohorts: @cohorts.to_h
+          cohorts: @cohorts.to_h,
+          minimal_flag_called_events: @minimal_flag_called_events
         }
         @flag_definition_cache_provider.on_flag_definitions_received(data)
       rescue StandardError => e
@@ -1218,6 +1253,7 @@ module PostHog
       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') || {}
+      minimal_flag_called_events = get_by_symbol_or_string_key(data, 'minimal_flag_called_events')
 
       @feature_flags = Concurrent::Array.new(flags.map { |f| deep_symbolize_keys(f) })
 
@@ -1229,9 +1265,10 @@ module PostHog
 
       @group_type_mapping = Concurrent::Hash[deep_symbolize_keys(group_type_mapping)]
       @cohorts = Concurrent::Hash[deep_symbolize_keys(cohorts)]
+      @minimal_flag_called_events = minimal_flag_called_events == true
 
       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/flag_definition_cache.rb

@@ -14,9 +14,11 @@ module PostHog
   #
   # @!method 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).
+  #   +:group_type_mapping+, +:cohorts+, and +:minimal_flag_called_events+
+  #   keys, or +nil+ if the cache is empty. Returning +nil+ triggers an API
+  #   fetch when no flags are loaded yet (emergency fallback). Providers
+  #   written before +:minimal_flag_called_events+ existed continue to work;
+  #   a missing key is treated as +false+.
   #   @return [Hash, nil]
   #
   # @!method should_fetch_flag_definitions?
@@ -27,9 +29,9 @@ module PostHog
   #
   # @!method 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.
+  #   +data+ is a Hash with +:flags+, +:group_type_mapping+, +:cohorts+, and
+  #   +:minimal_flag_called_events+ keys (plain Ruby types, not Concurrent::
+  #   wrappers). Store it in your external cache.
   #   @param data [Hash]
   #   @return [void]
   #

data/lib/posthog/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module PostHog
-  VERSION = '3.19.0'
+  VERSION = '3.21.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.21.0
 platform: ruby
 authors:
 - ''