posthog-ruby 3.1.1 → 3.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 47b1ce0c330a250b307dd757fa3024fcd516e8cf264576e52fde101c412d2e76
-  data.tar.gz: '08725cd78aab55aa87b70ebcf65a2a061b641cbab043a2df61552eff199cc534'
+  metadata.gz: 41c94649948ce4d629d17ccc7f5ed6649c7f9ed6e69ec491ca48bc638962cba4
+  data.tar.gz: 9a152790208aed756496e031faa0c2bf5a8dfba9bc8f74a1ac3510830132ac8a
 SHA512:
-  metadata.gz: 983808c3419cfab8772b3dbe175070d42dc10a357f1cb657bc36aa56389e867027e4c3ad3286d2d78eb2c232e2448f7190658beafcb846d2e5f72deb3d747d04
-  data.tar.gz: 92aab3899eb59d728170098b0b6ff62badffbcc890080c67eaf9657399f3de4f3c96d6241942ec1bf64b06bdc53e9dd588845a4c4cbe8b079759cbe51a71b0df
+  metadata.gz: b50f6538f3e285387f33a68a4c792c615f95d77826d333481637c7d3321a5490ce0be5f4bdf2ccb4ea914ae9ee5302dc488c9b3bf24f057a6c7d9c72799142d1
+  data.tar.gz: b34492ba3808627183010ca98d3e77356a873df98b5163854814e60f8225238db51cbafdb9786e9cf83a4295537c365e380094fe39d489bb518e979acd0578d4

data/bin/fmt

@@ -0,0 +1,14 @@
+#!/usr/bin/env bash
+#/ Usage: bin/fmt [--check]
+#/ Description: Format code using rubocop. Use --check to only check formatting without fixing.
+source bin/helpers/_utils.sh
+set_source_and_root_dir
+
+# Check if --check flag is provided
+if [[ "$1" == "--check" ]]; then
+    echo "Checking code formatting..."
+    rubocop
+else
+    echo "Formatting code with rubocop..."
+    rubocop --autocorrect-all
+fi

data/bin/test

@@ -4,4 +4,6 @@
 source bin/helpers/_utils.sh
 set_source_and_root_dir
 
-bundle exec rspec
+# Use RUBYLIB to avoid bundler dependency issues
+# This allows tests to run even if bundler can't resolve all dev dependencies
+RUBYLIB=lib rspec "$@"

data/lib/posthog/feature_flags.rb

@@ -30,6 +30,7 @@ module PostHog
       @host = host
       @feature_flags = Concurrent::Array.new
       @group_type_mapping = Concurrent::Hash.new
+      @cohorts = Concurrent::Hash.new
       @loaded_flags_successfully_once = Concurrent::AtomicBoolean.new
       @feature_flags_by_key = nil
       @feature_flag_request_timeout_seconds = feature_flag_request_timeout_seconds
@@ -185,7 +186,8 @@ module PostHog
 
       if !flag_was_locally_evaluated && !only_evaluate_locally
         begin
-          flags_data = get_all_flags_and_payloads(distinct_id, groups, person_properties, group_properties, false, true)
+          flags_data = get_all_flags_and_payloads(distinct_id, groups, person_properties, group_properties,
+                                                  only_evaluate_locally, true)
           if flags_data.key?(:featureFlags)
             flags = stringify_keys(flags_data[:featureFlags] || {})
             request_id = flags_data[:requestId]
@@ -367,13 +369,16 @@ module PostHog
       parsed_dt
     end
 
-    def self.match_property(property, property_values)
+    def self.match_property(property, property_values, cohort_properties = {})
       # only looks for matches where key exists in property_values
       # doesn't support operator is_not_set
 
       PostHog::Utils.symbolize_keys! property
       PostHog::Utils.symbolize_keys! property_values
 
+      # Handle cohort properties
+      return match_cohort(property, property_values, cohort_properties) if extract_value(property, :type) == 'cohort'
+
       key = property[:key].to_sym
       value = property[:value]
       operator = property[:operator] || 'exact'
@@ -443,17 +448,247 @@ module PostHog
       end
     end
 
-    private
+    def self.match_cohort(property, property_values, cohort_properties)
+      # Cohort properties are in the form of property groups like this:
+      # {
+      #   "cohort_id" => {
+      #     "type" => "AND|OR",
+      #     "values" => [{
+      #        "key" => "property_name", "value" => "property_value"
+      #     }]
+      #   }
+      # }
+      cohort_id = extract_value(property, :value).to_s
+      property_group = find_cohort_property(cohort_properties, cohort_id)
+
+      raise InconclusiveMatchError, "can't match cohort without a given cohort property value" unless property_group
+
+      match_property_group(property_group, property_values, cohort_properties)
+    end
+
+    def self.match_property_group(property_group, property_values, cohort_properties)
+      return true if property_group.nil? || property_group.empty?
+
+      group_type = extract_value(property_group, :type)
+      properties = extract_value(property_group, :values)
+
+      return true if properties.nil? || properties.empty?
+
+      if nested_property_group?(properties)
+        match_nested_property_group(properties, group_type, property_values, cohort_properties)
+      else
+        match_regular_property_group(properties, group_type, property_values, cohort_properties)
+      end
+    end
+
+    def self.extract_value(hash, key)
+      return nil unless hash.is_a?(Hash)
+
+      hash[key] || hash[key.to_s]
+    end
+
+    def self.find_cohort_property(cohort_properties, cohort_id)
+      return nil unless cohort_properties.is_a?(Hash)
+
+      cohort_properties[cohort_id] || cohort_properties[cohort_id.to_sym]
+    end
+
+    def self.nested_property_group?(properties)
+      return false unless properties&.any?
+
+      first_property = properties[0]
+      return false unless first_property.is_a?(Hash)
+
+      first_property.key?(:values) || first_property.key?('values')
+    end
+
+    def self.match_nested_property_group(properties, group_type, property_values, cohort_properties)
+      case group_type
+      when 'AND'
+        properties.each do |property|
+          return false unless match_property_group(property, property_values, cohort_properties)
+        end
+        true
+      when 'OR'
+        properties.each do |property|
+          return true if match_property_group(property, property_values, cohort_properties)
+        end
+        false
+      else
+        raise InconclusiveMatchError, "Unknown property group type: #{group_type}"
+      end
+    end
+
+    def self.match_regular_property_group(properties, group_type, property_values, cohort_properties)
+      # Validate group type upfront
+      raise InconclusiveMatchError, "Unknown property group type: #{group_type}" unless %w[AND OR].include?(group_type)
+
+      error_matching_locally = false
+
+      properties.each do |prop|
+        PostHog::Utils.symbolize_keys!(prop)
+
+        matches = match_property(prop, property_values, cohort_properties)
+
+        negated = prop[:negation] || false
+        final_result = negated ? !matches : matches
+
+        # Short-circuit based on group type
+        if group_type == 'AND'
+          return false unless final_result
+        elsif final_result # group_type == 'OR'
+          return true
+        end
+      rescue InconclusiveMatchError => e
+        PostHog::Logging.logger&.debug("Failed to compute property #{prop} locally: #{e}")
+        error_matching_locally = true
+      end
+
+      raise InconclusiveMatchError, "can't match cohort without a given cohort property value" if error_matching_locally
+
+      # If we reach here, return default based on group type
+      group_type == 'AND'
+    end
+
+    # Evaluates a flag dependency property according to the dependency chain algorithm.
+    #
+    # @param property [Hash] Flag property with type="flag" and dependency_chain
+    # @param evaluation_cache [Hash] Cache for storing evaluation results
+    # @param distinct_id [String] The distinct ID being evaluated
+    # @param properties [Hash] Person properties for evaluation
+    # @param cohort_properties [Hash] Cohort properties for evaluation
+    # @return [Boolean] True if all dependencies in the chain evaluate to true, false otherwise
+    def evaluate_flag_dependency(property, evaluation_cache, distinct_id, properties, cohort_properties)
+      if property[:operator] != 'flag_evaluates_to'
+        # Should never happen, but just in case
+        raise InconclusiveMatchError, "Operator #{property[:operator]} not supported for flag dependencies"
+      end
+
+      if @feature_flags_by_key.nil? || evaluation_cache.nil?
+        # Cannot evaluate flag dependencies without required context
+        raise InconclusiveMatchError,
+              "Cannot evaluate flag dependency on '#{property[:key] || 'unknown'}' " \
+              'without feature flags loaded or evaluation_cache'
+      end
+
+      # Check if dependency_chain is present - it should always be provided for flag dependencies
+      unless property.key?(:dependency_chain)
+        # Missing dependency_chain indicates malformed server data
+        raise InconclusiveMatchError,
+              "Flag dependency property for '#{property[:key] || 'unknown'}' " \
+              "is missing required 'dependency_chain' field"
+      end
+
+      dependency_chain = property[:dependency_chain]
+
+      # Handle circular dependency (empty chain means circular)
+      if dependency_chain.empty?
+        PostHog::Logging.logger&.debug("Circular dependency detected for flag: #{property[:key]}")
+        raise InconclusiveMatchError,
+              "Circular dependency detected for flag '#{property[:key] || 'unknown'}'"
+      end
+
+      # Evaluate all dependencies in the chain order
+      dependency_chain.each do |dep_flag_key|
+        unless evaluation_cache.key?(dep_flag_key)
+          # Need to evaluate this dependency first
+          dep_flag = @feature_flags_by_key[dep_flag_key]
+          if dep_flag.nil?
+            # Missing flag dependency - cannot evaluate locally
+            evaluation_cache[dep_flag_key] = nil
+            raise InconclusiveMatchError,
+                  "Cannot evaluate flag dependency '#{dep_flag_key}' - flag not found in local flags"
+          elsif !dep_flag[:active]
+            # Check if the flag is active (same check as in _compute_flag_locally)
+            evaluation_cache[dep_flag_key] = false
+          else
+            # Recursively evaluate the dependency using existing instance method
+            begin
+              dep_result = match_feature_flag_properties(
+                dep_flag,
+                distinct_id,
+                properties,
+                evaluation_cache,
+                cohort_properties
+              )
+              evaluation_cache[dep_flag_key] = dep_result
+            rescue InconclusiveMatchError => e
+              # If we can't evaluate a dependency, store nil and propagate the error
+              evaluation_cache[dep_flag_key] = nil
+              raise InconclusiveMatchError,
+                    "Cannot evaluate flag dependency '#{dep_flag_key}': #{e.message}"
+            end
+          end
+        end
+
+        # Check the cached result
+        cached_result = evaluation_cache[dep_flag_key]
+        if cached_result.nil?
+          # Previously inconclusive - raise error again
+          raise InconclusiveMatchError,
+                "Flag dependency '#{dep_flag_key}' was previously inconclusive"
+        elsif !cached_result
+          # Definitive False result - dependency failed
+          return false
+        end
+      end
+
+      # Get the expected value of the immediate dependency and the actual value
+      expected_value = property[:value]
+      # The flag we want to evaluate is defined by :key which should ALSO be the last key in the dependency chain
+      actual_value = evaluation_cache[property[:key]]
+
+      self.class.matches_dependency_value(expected_value, actual_value)
+    end
+
+    def self.matches_dependency_value(expected_value, actual_value)
+      # Check if the actual flag value matches the expected dependency value.
+      #
+      # - String variant case: check for exact match or boolean true
+      # - Boolean case: must match expected boolean value
+      #
+      # @param expected_value [Object] The expected value from the property
+      # @param actual_value [Object] The actual value returned by the flag evaluation
+      # @return [Boolean] True if the values match according to flag dependency rules
+
+      # String variant case - check for exact match or boolean true
+      if actual_value.is_a?(String) && !actual_value.empty?
+        if expected_value.is_a?(TrueClass) || expected_value.is_a?(FalseClass)
+          # Any variant matches boolean true
+          return expected_value
+        elsif expected_value.is_a?(String)
+          # variants are case-sensitive, hence our comparison is too
+          return actual_value == expected_value
+        else
+          return false
+        end
+
+      # Boolean case - must match expected boolean value
+      elsif actual_value.is_a?(TrueClass) || actual_value.is_a?(FalseClass)
+        return actual_value == expected_value if expected_value.is_a?(TrueClass) || expected_value.is_a?(FalseClass)
+      end
+
+      # Default case
+      false
+    end
+
+    private_class_method :extract_value, :find_cohort_property, :nested_property_group?,
+                         :match_nested_property_group, :match_regular_property_group
 
     def _compute_flag_locally(flag, distinct_id, groups = {}, person_properties = {}, group_properties = {})
       raise InconclusiveMatchError, 'Flag has experience continuity enabled' if flag[:ensure_experience_continuity]
 
       return false unless flag[:active]
 
+      # Create evaluation cache for flag dependencies
+      evaluation_cache = {}
+
       flag_filters = flag[:filters] || {}
 
       aggregation_group_type_index = flag_filters[:aggregation_group_type_index]
-      return match_feature_flag_properties(flag, distinct_id, person_properties) if aggregation_group_type_index.nil?
+      if aggregation_group_type_index.nil?
+        return match_feature_flag_properties(flag, distinct_id, person_properties, evaluation_cache, @cohorts)
+      end
 
       group_name = @group_type_mapping[aggregation_group_type_index.to_s.to_sym]
 
@@ -475,7 +710,8 @@ module PostHog
       end
 
       focused_group_properties = group_properties[group_name_symbol]
-      match_feature_flag_properties(flag, groups[group_name_symbol], focused_group_properties)
+      match_feature_flag_properties(flag, groups[group_name_symbol], focused_group_properties, evaluation_cache,
+                                    @cohorts)
     end
 
     def _compute_flag_payload_locally(key, match_value)
@@ -490,7 +726,7 @@ module PostHog
       response
     end
 
-    def match_feature_flag_properties(flag, distinct_id, properties)
+    def match_feature_flag_properties(flag, distinct_id, properties, evaluation_cache, cohort_properties = {})
       flag_filters = flag[:filters] || {}
 
       flag_conditions = flag_filters[:groups] || []
@@ -506,7 +742,7 @@ module PostHog
       # NOTE: This NEEDS to be `each` because `each_key` breaks
       # This is not a hash, it's just an array with 2 entries
       sorted_flag_conditions.each do |condition, _idx| # rubocop:disable Style/HashEachMethods
-        if is_condition_match(flag, distinct_id, condition, properties)
+        if condition_match(flag, distinct_id, condition, properties, evaluation_cache, cohort_properties)
           variant_override = condition[:variant]
           flag_multivariate = flag_filters[:multivariate] || {}
           flag_variants = flag_multivariate[:variants] || []
@@ -532,26 +768,21 @@ module PostHog
       false
     end
 
-    # TODO: Rename to `condition_match?` in future version
-    def is_condition_match(flag, distinct_id, condition, properties) # rubocop:disable Naming/PredicateName
+    def condition_match(flag, distinct_id, condition, properties, evaluation_cache, cohort_properties = {})
       rollout_percentage = condition[:rollout_percentage]
 
       unless (condition[:properties] || []).empty?
-        if !condition[:properties].all? do |prop|
-          # Skip flag dependencies as they are not supported in local evaluation
+        unless condition[:properties].all? do |prop|
           if prop[:type] == 'flag'
-            logger.warn(
-              '[FEATURE FLAGS] Flag dependency filters are not supported in local evaluation. ' \
-              "Skipping condition for flag '#{flag[:key]}' with dependency on flag '#{prop[:key]}'"
-            )
-            next true
+            evaluate_flag_dependency(prop, evaluation_cache, distinct_id, properties, cohort_properties)
+          else
+            FeatureFlagsPoller.match_property(prop, properties, cohort_properties)
           end
-          FeatureFlagsPoller.match_property(prop, properties)
         end
           return false
-        elsif rollout_percentage.nil?
-          return true
         end
+
+        return true if rollout_percentage.nil?
       end
 
       return false if !rollout_percentage.nil? && (_hash(flag[:key], distinct_id) > (rollout_percentage.to_f / 100))
@@ -607,6 +838,7 @@ module PostHog
         @feature_flags = Concurrent::Array.new
         @feature_flags_by_key = {}
         @group_type_mapping = Concurrent::Hash.new
+        @cohorts = Concurrent::Hash.new
         @loaded_flags_successfully_once.make_false
         @quota_limited.make_true
         return
@@ -619,8 +851,9 @@ module PostHog
           @feature_flags_by_key[flag[:key]] = flag unless flag[:key].nil?
         end
         @group_type_mapping = res[:group_type_mapping] || {}
+        @cohorts = res[:cohorts] || {}
 
-        logger.debug "Loaded #{@feature_flags.length} feature flags"
+        logger.debug "Loaded #{@feature_flags.length} feature flags and #{@cohorts.length} cohorts"
         @loaded_flags_successfully_once.make_true if @loaded_flags_successfully_once.false?
       else
         logger.debug "Failed to load feature flags: #{res}"
@@ -629,7 +862,7 @@ module PostHog
 
     def _request_feature_flag_definitions
       uri = URI("#{@host}/api/feature_flag/local_evaluation")
-      uri.query = URI.encode_www_form([['token', @project_api_key]])
+      uri.query = URI.encode_www_form([['token', @project_api_key], %w[send_cohorts true]])
       req = Net::HTTP::Get.new(uri)
       req['Authorization'] = "Bearer #{@personal_api_key}"
 

data/lib/posthog/version.rb

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

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: posthog-ruby
 version: !ruby/object:Gem::Version
-  version: 3.1.1
+  version: 3.2.0
 platform: ruby
 authors:
 - ''
 bindir: bin
 cert_chain: []
-date: 2025-08-07 00:00:00.000000000 Z
+date: 2025-08-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: concurrent-ruby
@@ -30,6 +30,7 @@ executables:
 extensions: []
 extra_rdoc_files: []
 files:
+- bin/fmt
 - bin/helpers/_utils.sh
 - bin/posthog
 - bin/test