posthog-ruby 3.27.1 → 3.28.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 125a7a9c4063477324ed9654c1035ff28e959cb6c389dfbcfc5ee08bb17153ab
-  data.tar.gz: b02e50631f58cb0e119184c1556766c55ee0e1ae578514620b6217a916207b7e
+  metadata.gz: 561f4ebad1a6cd75904b800f540c0dbb9352cc081dc57bf5cc0a5dcb82925e89
+  data.tar.gz: 5e9ce62f5e48c5380ce71e454507bafa6825a8e7e6db6c05b8896b8c5a665c62
 SHA512:
-  metadata.gz: 1adee637ab5766731429e73e4bd41b102c9bb33fc285b75b4a62dd173a6fa0c4825ee47ff87b007d8cc8c517c8eab6103b33337b62fd4504497c2c127580c7c2
-  data.tar.gz: 82c8accf93eede6fe7c4748967377b7fa9a1ffc28f7c9ed85e6355ba81d2312962767488436af285c57e0bfc9ebcd442dd486157644b708e9dbd03ad045fd712
+  metadata.gz: 41f3fde35a6e73ffa54b09fff2d88990057a3fac677153b2e14e6547fb20dbacebcc7a687bae432a98c62cabad572b5dc64cc57fb0cfbab554d7c72581d84ab8
+  data.tar.gz: e596b42169af511879c3397bc6e42aa2410bee4aa4d519b6958ad87d0800da67e6b208670abd809f4bd34d52616db2fd9a1d1ae3b3b8ebdf4c867edfb5ad186f

data/lib/posthog/feature_flags.rb

@@ -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|

data/lib/posthog/version.rb

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