posthog-ruby 3.1.2 → 3.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 73269e57e35a55b2ff07748aa4cab6da17c37b42d64a170528cb5dd1955a9365
-  data.tar.gz: 831672593c8646bb05fae81c527a0e64016d3fbae42e722a6525988ce3257b73
+  metadata.gz: e895ef67d6f423e89151951d6868fa464c1efe64cee6dd37be8923351bf88467
+  data.tar.gz: 7bf79b2a93e79c8717e52ed2a6ca3261f0d3933859e05e0cee1c9c22aaaa77db
 SHA512:
-  metadata.gz: 6805d61de4837441d2b4a333f76e093cac6668e2cbf9dba88fa1602f02ce7fedd28ab5cf433217bc1d40127bcf73e2f7ccebeaeb8086a98ec45a5c26b139b030
-  data.tar.gz: ec9ad7127fe2d0b6d78e1c6f9f28e4ccaf3c99362edc8f20e1b8f06afe56cbc84538bc9bcbc4acbce4d81a546e6046acddfb1cc0ac5ba5cba5f52b04446d467b
+  metadata.gz: 881cd65e3634adc8fe539fad751591876ffd070ed712b4de8533fdf38e231ba15fd126daa0afece1b1f06b27306c3afa00c1129e37c98202391593f439cfa886
+  data.tar.gz: 2333ef174f7f08858cf518d66ac60bd6c5fa8246d06b61c73c89c5e7d08cf2986b5b45bc952d6d18476b3b73257402ee5838a362da100da1b64d7c72f4ae38eb

data/lib/posthog/client.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'time'
+require 'securerandom'
 
 require 'posthog/defaults'
 require 'posthog/logging'
@@ -9,6 +10,7 @@ require 'posthog/send_worker'
 require 'posthog/noop_worker'
 require 'posthog/feature_flags'
 require 'posthog/send_feature_flags_options'
+require 'posthog/exception_capture'
 
 module PostHog
   class Client
@@ -144,6 +146,33 @@ module PostHog
       enqueue(FieldParser.parse_for_capture(attrs))
     end
 
+    # Captures an exception as an event
+    #
+    # @param [Exception, String, Object] exception The exception to capture, a string message, or exception-like object
+    # @param [String] distinct_id The ID for the user (optional, defaults to a generated UUID)
+    # @param [Hash] additional_properties Additional properties to include with the exception event (optional)
+    def capture_exception(exception, distinct_id = nil, additional_properties = {})
+      exception_info = ExceptionCapture.build_parsed_exception(exception)
+
+      return if exception_info.nil?
+
+      no_distinct_id_was_provided = distinct_id.nil?
+      distinct_id ||= SecureRandom.uuid
+
+      properties = { '$exception_list' => [exception_info] }
+      properties.merge!(additional_properties) if additional_properties && !additional_properties.empty?
+      properties['$process_person_profile'] = false if no_distinct_id_was_provided
+
+      event_data = {
+        distinct_id: distinct_id,
+        event: '$exception',
+        properties: properties,
+        timestamp: Time.now
+      }
+
+      capture(event_data)
+    end
+
     # Identifies a user
     #
     # @param [Hash] attrs

data/lib/posthog/exception_capture.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+# Portions of this file are derived from getsentry/sentry-ruby by Software, Inc. dba Sentry
+# Licensed under the MIT License
+# - sentry-ruby/lib/sentry/interfaces/single_exception.rb
+# - sentry-ruby/lib/sentry/interfaces/stacktrace_builder.rb
+# - sentry-ruby/lib/sentry/backtrace.rb
+# - sentry-ruby/lib/sentry/interfaces/stacktrace.rb
+# - sentry-ruby/lib/sentry/linecache.rb
+
+# 💖 open source (under MIT License)
+
+module PostHog
+  module ExceptionCapture
+    RUBY_INPUT_FORMAT = /
+        ^ \s* (?: [a-zA-Z]: | uri:classloader: )? ([^:]+ | <.*>):
+        (\d+)
+        (?: :in\s('|`)(?:([\w:]+)\#)?([^']+)')?$
+      /x
+
+    def self.build_parsed_exception(value)
+      title, message, backtrace = coerce_exception_input(value)
+      return nil if title.nil?
+
+      build_single_exception_from_data(title, message, backtrace)
+    end
+
+    def self.build_single_exception_from_data(title, message, backtrace)
+      {
+        'type' => title,
+        'value' => message || '',
+        'mechanism' => {
+          'type' => 'generic',
+          'handled' => true
+        },
+        'stacktrace' => build_stacktrace(backtrace)
+      }
+    end
+
+    def self.build_stacktrace(backtrace)
+      return nil unless backtrace && !backtrace.empty?
+
+      frames = backtrace.first(50).map do |line|
+        parse_backtrace_line(line)
+      end.compact.reverse
+
+      {
+        'type' => 'raw',
+        'frames' => frames
+      }
+    end
+
+    def self.parse_backtrace_line(line)
+      match = line.match(RUBY_INPUT_FORMAT)
+      return nil unless match
+
+      file = match[1]
+      lineno = match[2].to_i
+      method_name = match[5]
+
+      frame = {
+        'filename' => File.basename(file),
+        'abs_path' => file,
+        'lineno' => lineno,
+        'function' => method_name,
+        'in_app' => !gem_path?(file),
+        'platform' => 'ruby'
+      }
+
+      add_context_lines(frame, file, lineno) if File.exist?(file)
+
+      frame
+    end
+
+    def self.gem_path?(path)
+      path.include?('/gems/') ||
+        path.include?('/ruby/') ||
+        path.include?('/.rbenv/') ||
+        path.include?('/.rvm/')
+    end
+
+    def self.add_context_lines(frame, file_path, lineno, context_size = 5)
+      lines = File.readlines(file_path)
+      return if lines.empty?
+
+      return unless lineno.positive? && lineno <= lines.length
+
+      pre_context_start = [lineno - context_size, 1].max
+      post_context_end = [lineno + context_size, lines.length].min
+
+      frame['context_line'] = lines[lineno - 1].chomp
+
+      frame['pre_context'] = lines[(pre_context_start - 1)...(lineno - 1)].map(&:chomp) if pre_context_start < lineno
+
+      frame['post_context'] = lines[lineno...(post_context_end)].map(&:chomp) if post_context_end > lineno
+    rescue StandardError
+      # Silently ignore file read errors
+    end
+
+    def self.coerce_exception_input(value)
+      if value.is_a?(String)
+        title = 'Error'
+        message = value
+        backtrace = nil
+      elsif value.respond_to?(:backtrace) && value.respond_to?(:message)
+        title = value.class.to_s
+        message = value.message || ''
+        backtrace = value.backtrace
+      else
+        return [nil, nil, nil]
+      end
+
+      [title, message, backtrace]
+    end
+  end
+end

data/lib/posthog/feature_flags.rb

@@ -186,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]
@@ -526,8 +527,8 @@ module PostHog
 
       properties.each do |prop|
         PostHog::Utils.symbolize_keys!(prop)
-        matches = evaluate_property_match(prop, property_values, cohort_properties)
-        next if matches.nil? # Skip flag dependencies
+
+        matches = match_property(prop, property_values, cohort_properties)
 
         negated = prop[:negation] || false
         final_result = negated ? !matches : matches
@@ -549,37 +550,144 @@ module PostHog
       group_type == 'AND'
     end
 
-    def self.evaluate_property_match(prop, property_values, cohort_properties)
-      prop_type = extract_value(prop, :type)
+    # 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
 
-      case prop_type
-      when 'cohort'
-        match_cohort(prop, property_values, cohort_properties)
-      when 'flag'
-        PostHog::Logging.logger&.warn(
-          '[FEATURE FLAGS] Flag dependency filters are not supported in local evaluation. ' \
-          "Skipping condition with dependency on flag '#{prop[:key]}'"
-        )
-        nil # Signal to skip this property
-      else
-        match_property(prop, property_values, cohort_properties)
+        # 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, :evaluate_property_match
+                         :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]
       if aggregation_group_type_index.nil?
-        return match_feature_flag_properties(flag, distinct_id, person_properties,
-                                             @cohorts)
+        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]
@@ -602,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, @cohorts)
+      match_feature_flag_properties(flag, groups[group_name_symbol], focused_group_properties, evaluation_cache,
+                                    @cohorts)
     end
 
     def _compute_flag_payload_locally(key, match_value)
@@ -617,7 +726,7 @@ module PostHog
       response
     end
 
-    def match_feature_flag_properties(flag, distinct_id, properties, cohort_properties = {})
+    def match_feature_flag_properties(flag, distinct_id, properties, evaluation_cache, cohort_properties = {})
       flag_filters = flag[:filters] || {}
 
       flag_conditions = flag_filters[:groups] || []
@@ -633,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, cohort_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] || []
@@ -659,26 +768,21 @@ module PostHog
       false
     end
 
-    # TODO: Rename to `condition_match?` in future version
-    def is_condition_match(flag, distinct_id, condition, properties, cohort_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, cohort_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))

data/lib/posthog/version.rb

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

data/lib/posthog.rb

@@ -9,3 +9,4 @@ require 'posthog/send_worker'
 require 'posthog/transport'
 require 'posthog/response'
 require 'posthog/logging'
+require 'posthog/exception_capture'

metadata

@@ -1,13 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: posthog-ruby
 version: !ruby/object:Gem::Version
-  version: 3.1.2
+  version: 3.3.0
 platform: ruby
 authors:
 - ''
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-08-13 00:00:00.000000000 Z
+date: 2025-09-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: concurrent-ruby
@@ -38,6 +39,7 @@ files:
 - lib/posthog/backoff_policy.rb
 - lib/posthog/client.rb
 - lib/posthog/defaults.rb
+- lib/posthog/exception_capture.rb
 - lib/posthog/feature_flag.rb
 - lib/posthog/feature_flags.rb
 - lib/posthog/field_parser.rb
@@ -55,6 +57,7 @@ licenses:
 - MIT
 metadata:
   rubygems_mfa_required: 'true'
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -69,7 +72,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.6
+rubygems_version: 3.5.3
+signing_key:
 specification_version: 4
 summary: PostHog library
 test_files: []