posthog-ruby 3.27.0 → 3.28.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9809cd9248724a9b3b032b1f822c7108da7a089330f37bacd1c86d7b614452e2
-  data.tar.gz: ca0f1dfcaecfbbaa4cf426ca0ab9eda422dede368cf55e899bb2aeb6e4a5b0ab
+  metadata.gz: 561f4ebad1a6cd75904b800f540c0dbb9352cc081dc57bf5cc0a5dcb82925e89
+  data.tar.gz: 5e9ce62f5e48c5380ce71e454507bafa6825a8e7e6db6c05b8896b8c5a665c62
 SHA512:
-  metadata.gz: 0c291a4b34b4d060bd0f85f0fe9622b5ee209b2f888dfff1b049108a63bc8bb8ee0f302218bffb20e71e31d04561b00dede786bb8dc57bced15d52578ca9a2dd
-  data.tar.gz: 8acdfca32f6df2ee0d9330539715bbc1d29b23a14c7ca6d2a458f6f8857d50ea9318d1f2d4c27354967c91abf5cc0ba87519d3255e5be849c5b3e78fd24d232f
+  metadata.gz: 41f3fde35a6e73ffa54b09fff2d88990057a3fac677153b2e14e6547fb20dbacebcc7a687bae432a98c62cabad572b5dc64cc57fb0cfbab554d7c72581d84ab8
+  data.tar.gz: e596b42169af511879c3397bc6e42aa2410bee4aa4d519b6958ad87d0800da67e6b208670abd809f4bd34d52616db2fd9a1d1ae3b3b8ebdf4c867edfb5ad186f

data/lib/posthog/client.rb

@@ -85,9 +85,9 @@ module PostHog
 
     # @param opts [Hash] Client configuration.
     # @option opts [String, nil] :api_key Your project's API key. Missing or blank values disable the client.
-    # @option opts [String, nil] :secret_key The credential used for local feature flag evaluation and remote
-    #   config. Accepts either a Personal API Key (`phx_...`) or a Project Secret API Key (`phs_...`). Required
-    #   for local feature flag evaluation.
+    # @option opts [String, nil] :secret_key The credential used to fetch local feature flag definitions and remote
+    #   config. Accepts either a Personal API Key (`phx_...`) or a Project Secret API Key (`phs_...`). Not required
+    #   for local evaluation when definitions are read from +:flag_definition_cache_provider+.
     # @option opts [String, nil] :personal_api_key
     #   @deprecated Use +:secret_key+ instead. Retained as an alias; when both are supplied, +:secret_key+ wins.
     # @option opts [String] :host Fully qualified hostname of the PostHog server. Defaults to `https://us.i.posthog.com`.
@@ -180,6 +180,7 @@ module PostHog
       @feature_flags_poller = nil
       @secret_key = secret_key
       @personal_api_key = secret_key
+      @flag_definition_cache_provider = opts[:flag_definition_cache_provider]
 
       if @disabled && !opts[:silence_disabled_client_error]
         logger.error('api_key is missing or empty after trimming whitespace; check your project API key')
@@ -214,7 +215,7 @@ module PostHog
             opts[:host],
             opts[:feature_flag_request_timeout_seconds] || Defaults::FeatureFlags::FLAG_REQUEST_TIMEOUT_SECONDS,
             opts[:on_error],
-            flag_definition_cache_provider: opts[:flag_definition_cache_provider],
+            flag_definition_cache_provider: @flag_definition_cache_provider,
             feature_flag_request_max_retries: opts[:feature_flag_request_max_retries],
             async_load: opts[:feature_flags_async_load] == true,
             user_agent: @headers['User-Agent'],
@@ -883,9 +884,9 @@ module PostHog
     def reload_feature_flags
       return if @disabled
 
-      unless @secret_key
+      unless @secret_key || @flag_definition_cache_provider
         logger.error(
-          'You need to specify a secret_key to locally evaluate feature flags'
+          'You need to specify a secret_key or flag_definition_cache_provider to locally evaluate feature flags'
         )
         return
       end

data/lib/posthog/feature_flags.rb

@@ -100,9 +100,9 @@ module PostHog
           run_now: @async_load
         ) { _load_feature_flags }
 
-      # If no secret_key, disable local evaluation & thus polling for definitions
-      if @secret_key.nil?
-        logger.info 'No secret_key provided, disabling local evaluation'
+      # Local evaluation can load definitions from either the API or an external cache.
+      if @secret_key.nil? && @flag_definition_cache_provider.nil?
+        logger.info 'No secret_key or flag_definition_cache_provider provided, disabling local evaluation'
         @loaded_flags_successfully_once.make_true
       else
         # load once synchronously before timer, unless @async_load
@@ -1110,6 +1110,13 @@ module PostHog
                                       groups: {}, group_properties: {}, snapshot: _evaluation_snapshot)
       flag_filters = flag[:filters] || {}
 
+      # Holdouts precede release conditions: a held-out identifier is excluded from
+      # the flag's targeting entirely rather than bucketed into one of its variants.
+      # The per-condition aggregation handled below never changes holdout membership,
+      # so this uses the flag-level bucketing identity the caller resolved.
+      holdout_variant = holdout_variant_for(flag_filters[:holdout], distinct_id)
+      return holdout_variant unless holdout_variant.nil?
+
       flag_conditions = flag_filters[:groups] || []
       flag_aggregation = flag_filters[:aggregation_group_type_index]
       early_exit = flag_filters[:early_exit] == true
@@ -1233,6 +1240,36 @@ module PostHog
       (Integer(hash_key[0..14], 16).to_f / 0xfffffffffffffff)
     end
 
+    # An experiment holdout excludes an identifier from the flag's release conditions
+    # entirely, resolving it to the synthetic variant "holdout-<id>". That variant does
+    # not need to exist in `filters.multivariate.variants`. Returns nil when the flag has
+    # no usable holdout or the identifier falls outside it, leaving ordinary evaluation
+    # unchanged.
+    def holdout_variant_for(holdout, bucketing_value)
+      return nil unless holdout.is_a?(Hash)
+
+      id = holdout[:id]
+      exclusion_percentage = holdout[:exclusion_percentage]
+      return nil if id.nil? || !exclusion_percentage.is_a?(Numeric)
+
+      # The server clamps an out-of-range percentage rather than rejecting it, and treats
+      # 100 as everyone without hashing, so a full holdout can't miss on a hash boundary.
+      # Fractional percentages are kept as-is.
+      percentage = exclusion_percentage.to_f.clamp(0, 100)
+      return nil if percentage < 100 && _holdout_hash(bucketing_value) > (percentage / 100)
+
+      "holdout-#{id}"
+    end
+
+    # Holdout membership hashes `holdout-<bucketing value>` with no separator, salt, flag
+    # key or holdout id taking part, so one identity lands in the same holdout population
+    # on every flag, the way the server buckets it. The dot-separated flag hash above
+    # selects a different population and must not be reused here.
+    def _holdout_hash(bucketing_value)
+      hash_key = Digest::SHA1.hexdigest "holdout-#{bucketing_value}"
+      (Integer(hash_key[0..14], 16).to_f / 0xfffffffffffffff)
+    end
+
     def get_matching_variant(flag, distinct_id)
       hash_value = _hash(flag[:key], distinct_id, 'variant')
       matching_variant = variant_lookup_table(flag).find do |variant|
@@ -1260,7 +1297,8 @@ module PostHog
 
       if @flag_definition_cache_provider
         begin
-          should_fetch = @flag_definition_cache_provider.should_fetch_flag_definitions?
+          # Cache-only readers must not acquire or renew fetch leadership.
+          should_fetch = @secret_key && @flag_definition_cache_provider.should_fetch_flag_definitions?
         rescue StandardError => e
           logger.error("[FEATURE FLAGS] Cache provider should_fetch error: #{e}")
           should_fetch = true
@@ -1271,6 +1309,10 @@ module PostHog
         begin
           cached_data = @flag_definition_cache_provider.flag_definitions
           if cached_data
+            unless cached_data.is_a?(Hash) && get_by_symbol_or_string_key(cached_data, 'flags').is_a?(Array)
+              raise ArgumentError, 'Cached flag definitions must contain a flags array'
+            end
+
             logger.debug '[FEATURE FLAGS] Using cached flag definitions from external cache'
             _apply_flag_definitions(cached_data)
             return
@@ -1288,6 +1330,11 @@ module PostHog
     end
 
     def _fetch_and_apply_flag_definitions
+      unless @secret_key
+        logger.warn '[FEATURE FLAGS] A secret_key is required to fetch flag definitions from PostHog'
+        return
+      end
+
       begin
         res = _request_feature_flag_definitions(etag: @flags_etag.value)
       rescue StandardError => e

data/lib/posthog/flag_definition_cache.rb

@@ -5,7 +5,8 @@ module PostHog
   #
   # Enables multi-worker environments (Kubernetes, load-balanced servers,
   # serverless functions) to share flag definitions via an external cache,
-  # reducing redundant API calls.
+  # reducing redundant API calls. Cache consumers need only the project API key;
+  # +:secret_key+ is required only for workers that fetch definitions from PostHog.
   #
   # Implement the four required methods on any object and pass it as the
   # +:flag_definition_cache_provider+ option when creating a {Client}.
@@ -16,7 +17,7 @@ module PostHog
   #   Retrieve cached flag definitions. Return a Hash with +:flags+,
   #   +:group_type_mapping+, +:cohorts+, +:minimal_flag_called_events+, and +:property_matching_version+
   #   keys, or +nil+ if the cache is empty. Returning +nil+ triggers an API
-  #   fetch when no flags are loaded yet (emergency fallback). Providers
+  #   fetch when no flags are loaded yet and +:secret_key+ is configured (emergency fallback). Providers
   #   written before +:minimal_flag_called_events+ existed continue to work;
   #   a missing key is treated as +false+. Preserve +:property_matching_version+
   #   with the definitions: exactly +2+ selects explicit equality; missing/1
@@ -27,7 +28,9 @@ module PostHog
   # @!method 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.
+  #   coordination so only one worker fetches at a time. Called only when
+  #   +:secret_key+ is configured. Without it, the SDK reads +flag_definitions+
+  #   directly without acquiring or renewing fetch leadership.
   #   @return [Boolean]
   #
   # @!method on_flag_definitions_received(data)
@@ -53,12 +56,16 @@ module PostHog
   # - +on_flag_definitions_received+ errors are logged; flags remain in memory
   # - +shutdown+ errors are logged; shutdown continues
   #
+  # API fallback requires +:secret_key+. Without it, the SDK logs a warning and
+  # keeps any previously loaded definitions. Cache-only readers skip the fetch
+  # decision and never publish. Polling and manual reloads continue reading the
+  # cache so consumers can pick up later updates.
+  #
   # == Example
   #
   #   cache = RedisFlagCache.new(redis, service_key: 'my-service')
   #   client = PostHog::Client.new(
   #     api_key: '<project_api_key>',
-  #     secret_key: '<secret_key>',
   #     flag_definition_cache_provider: cache
   #   )
   #

data/lib/posthog/version.rb

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

metadata

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