posthog-ruby 3.3.2 → 3.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9df507c0722b4e1f6d12810813f6f8d37d24473a034ef067889d83edc3106dcc
-  data.tar.gz: c576573a7eef9476b9d16905b7bf26f249ed10ef4cb12691746de161dec9277d
+  metadata.gz: 9e99287bd9fe6eb8969c2481c0380c2a6eba12709de5f5189a053cb9ba5ca255
+  data.tar.gz: 78b496c5feb9c8cb222393ababa36d0f6fd81c18e603469b0633ac3fcdbfd639
 SHA512:
-  metadata.gz: a2b8b07133cef4a959d79db0ec354fa8437f72b7e312240a41af44820e6663f7595da661c6b3e172885b7766f8f5f07ba35ee21d1795c564c09838358647d1cc
-  data.tar.gz: af0218271ebf8de7d45e289176e941d0e72e7871df5d3438f2c30d4f423170125d3b54e89ae4bf05ba63d80fbb9981b0e4a7acf02dfeb2fa17d7891dcf29d02e
+  metadata.gz: dc1c52ff0243af441d895c05199067347931f0bf50a21ba897a3fb75640cb954ec66c79dddb29fb92338479014f3a7f42543a1ef651ebdcbd7fe6845ff9e9002
+  data.tar.gz: e46932963b504e54fe4590db73e1956611190b2ab16a1f04ffff5877c01b1e71a2dafc5f9c373361b69bb5f63532d1400c244580ac3c229ced006b350880eef5

data/lib/posthog/client.rb

@@ -285,26 +285,31 @@ module PostHog
         person_properties,
         group_properties
       )
-      feature_flag_response, flag_was_locally_evaluated, request_id = @feature_flags_poller.get_feature_flag(
-        key,
-        distinct_id,
-        groups,
-        person_properties,
-        group_properties,
-        only_evaluate_locally
-      )
+      feature_flag_response, flag_was_locally_evaluated, request_id, evaluated_at =
+        @feature_flags_poller.get_feature_flag(
+          key,
+          distinct_id,
+          groups,
+          person_properties,
+          group_properties,
+          only_evaluate_locally
+        )
 
       feature_flag_reported_key = "#{key}_#{feature_flag_response}"
       if !@distinct_id_has_sent_flag_calls[distinct_id].include?(feature_flag_reported_key) && send_feature_flag_events
+        properties = {
+          '$feature_flag' => key,
+          '$feature_flag_response' => feature_flag_response,
+          'locally_evaluated' => flag_was_locally_evaluated
+        }
+        properties['$feature_flag_request_id'] = request_id if request_id
+        properties['$feature_flag_evaluated_at'] = evaluated_at if evaluated_at
+
         capture(
           {
             distinct_id: distinct_id,
             event: '$feature_flag_called',
-            properties: {
-              '$feature_flag' => key,
-              '$feature_flag_response' => feature_flag_response,
-              'locally_evaluated' => flag_was_locally_evaluated
-            }.merge(request_id ? { '$feature_flag_request_id' => request_id } : {}),
+            properties: properties,
             groups: groups
           }
         )
@@ -385,7 +390,9 @@ module PostHog
         distinct_id, groups, person_properties, group_properties, only_evaluate_locally
       )
 
-      response.delete(:requestId) # remove internal information.
+      # Remove internal information
+      response.delete(:requestId)
+      response.delete(:evaluatedAt)
       response
     end
 

data/lib/posthog/feature_flags.rb

@@ -12,6 +12,13 @@ module PostHog
   class InconclusiveMatchError < StandardError
   end
 
+  # RequiresServerEvaluation is raised when feature flag evaluation requires
+  # server-side data that is not available locally (e.g., static cohorts,
+  # experience continuity). This error should propagate immediately to trigger
+  # API fallback, unlike InconclusiveMatchError which allows trying other conditions.
+  class RequiresServerEvaluation < StandardError
+  end
+
   class FeatureFlagsPoller
     include PostHog::Logging
     include PostHog::Utils
@@ -36,6 +43,7 @@ module PostHog
       @feature_flag_request_timeout_seconds = feature_flag_request_timeout_seconds
       @on_error = on_error || proc { |status, error| }
       @quota_limited = Concurrent::AtomicBoolean.new(false)
+      @flags_etag = Concurrent::AtomicReference.new(nil)
       @task =
         Concurrent::TimerTask.new(
           execution_interval: polling_interval
@@ -133,6 +141,7 @@ module PostHog
           [key, FeatureFlag.from_value_and_payload(key, value, flags_response[:featureFlagPayloads][key])]
         end
       end
+
       flags_response
     end
 
@@ -173,7 +182,7 @@ module PostHog
         begin
           response = _compute_flag_locally(feature_flag, distinct_id, groups, person_properties, group_properties)
           logger.debug "Successfully computed flag locally: #{key} -> #{response}"
-        rescue InconclusiveMatchError => e
+        rescue RequiresServerEvaluation, InconclusiveMatchError => e
           logger.debug "Failed to compute flag #{key} locally: #{e}"
         rescue StandardError => e
           @on_error.call(-1, "Error computing flag locally: #{e}. #{e.backtrace.join("\n")}")
@@ -183,6 +192,7 @@ module PostHog
       flag_was_locally_evaluated = !response.nil?
 
       request_id = nil
+      evaluated_at = nil
 
       if !flag_was_locally_evaluated && !only_evaluate_locally
         begin
@@ -191,6 +201,7 @@ module PostHog
           if flags_data.key?(:featureFlags)
             flags = stringify_keys(flags_data[:featureFlags] || {})
             request_id = flags_data[:requestId]
+            evaluated_at = flags_data[:evaluatedAt]
           else
             logger.debug "Missing feature flags key: #{flags_data.to_json}"
             flags = {}
@@ -204,7 +215,7 @@ module PostHog
         end
       end
 
-      [response, flag_was_locally_evaluated, request_id]
+      [response, flag_was_locally_evaluated, request_id, evaluated_at]
     end
 
     def get_all_flags(
@@ -245,13 +256,14 @@ module PostHog
       payloads = {}
       fallback_to_server = @feature_flags.empty?
       request_id = nil # Only for /flags requests
+      evaluated_at = nil # Only for /flags requests
 
       @feature_flags.each do |flag|
         match_value = _compute_flag_locally(flag, distinct_id, groups, person_properties, group_properties)
         flags[flag[:key]] = match_value
         match_payload = _compute_flag_payload_locally(flag[:key], match_value)
         payloads[flag[:key]] = match_payload if match_payload
-      rescue InconclusiveMatchError
+      rescue RequiresServerEvaluation, InconclusiveMatchError
         fallback_to_server = true
       rescue StandardError => e
         @on_error.call(-1, "Error computing flag locally: #{e}. #{e.backtrace.join("\n")} ")
@@ -275,6 +287,7 @@ module PostHog
             flags = stringify_keys(flags_and_payloads[:featureFlags] || {})
             payloads = stringify_keys(flags_and_payloads[:featureFlagPayloads] || {})
             request_id = flags_and_payloads[:requestId]
+            evaluated_at = flags_and_payloads[:evaluatedAt]
           end
         rescue StandardError => e
           @on_error.call(-1, "Error computing flag remotely: #{e}")
@@ -285,7 +298,8 @@ module PostHog
       {
         featureFlags: flags,
         featureFlagPayloads: payloads,
-        requestId: request_id
+        requestId: request_id,
+        evaluatedAt: evaluated_at
       }
     end
 
@@ -461,7 +475,10 @@ module PostHog
       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
+      unless property_group
+        raise RequiresServerEvaluation,
+              "cohort #{cohort_id} not found in local cohorts - likely a static cohort that requires server evaluation"
+      end
 
       match_property_group(property_group, property_values, cohort_properties)
     end
@@ -539,6 +556,9 @@ module PostHog
         elsif final_result # group_type == 'OR'
           return true
         end
+      rescue RequiresServerEvaluation
+        # Immediately propagate - this condition requires server-side data
+        raise
       rescue InconclusiveMatchError => e
         PostHog::Logging.logger&.debug("Failed to compute property #{prop} locally: #{e}")
         error_matching_locally = true
@@ -676,7 +696,7 @@ module PostHog
                          :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]
+      raise RequiresServerEvaluation, 'Flag has experience continuity enabled' if flag[:ensure_experience_continuity]
 
       return false unless flag[:active]
 
@@ -747,7 +767,12 @@ module PostHog
           result = variant || true
           break
         end
+      rescue RequiresServerEvaluation
+        # Static cohort or other missing server-side data - must fallback to API
+        raise
       rescue InconclusiveMatchError
+        # Evaluation error (bad regex, invalid date, missing property, etc.)
+        # Track that we had an inconclusive match, but try other conditions
         is_inconclusive = true
       end
 
@@ -816,12 +841,20 @@ module PostHog
 
     def _load_feature_flags
       begin
-        res = _request_feature_flag_definitions
+        res = _request_feature_flag_definitions(etag: @flags_etag.value)
       rescue StandardError => e
         @on_error.call(-1, e.to_s)
         return
       end
 
+      # Handle 304 Not Modified - flags haven't changed, skip processing
+      # Only update ETag if the 304 response includes one
+      if res[:not_modified]
+        @flags_etag.value = res[:etag] if res[:etag]
+        logger.debug '[FEATURE FLAGS] Flags not modified (304), using cached data'
+        return
+      end
+
       # Handle quota limits with 402 status
       if res.is_a?(Hash) && res[:status] == 402
         logger.warn(
@@ -838,6 +871,9 @@ module PostHog
       end
 
       if res.key?(:flags)
+        # Only update ETag on successful responses with flag data
+        @flags_etag.value = res[:etag]
+
         @feature_flags = res[:flags] || []
         @feature_flags_by_key = {}
         @feature_flags.each do |flag|
@@ -853,13 +889,14 @@ module PostHog
       end
     end
 
-    def _request_feature_flag_definitions
+    def _request_feature_flag_definitions(etag: nil)
       uri = URI("#{@host}/api/feature_flag/local_evaluation")
       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}"
+      req['If-None-Match'] = etag if etag
 
-      _request(uri, req)
+      _request(uri, req, nil, include_etag: true)
     end
 
     def _request_feature_flag_evaluation(data = {})
@@ -883,7 +920,7 @@ module PostHog
     end
 
     # rubocop:disable Lint/ShadowedException
-    def _request(uri, request_object, timeout = nil)
+    def _request(uri, request_object, timeout = nil, include_etag: false)
       request_object['User-Agent'] = "posthog-ruby#{PostHog::VERSION}"
       request_timeout = timeout || 10
 
@@ -895,16 +932,28 @@ module PostHog
           read_timeout: request_timeout
         ) do |http|
           res = http.request(request_object)
+          status_code = res.code.to_i
+          etag = include_etag ? res['ETag'] : nil
+
+          # Handle 304 Not Modified - return special response indicating no change
+          if status_code == 304
+            logger.debug("#{request_object.method} #{_mask_tokens_in_url(uri.to_s)} returned 304 Not Modified")
+            return { not_modified: true, etag: etag, status: status_code }
+          end
 
           # Parse response body to hash
           begin
             response = JSON.parse(res.body, { symbolize_names: true })
-            # Only add status if response is a hash
-            response = response.merge({ status: res.code.to_i }) if response.is_a?(Hash)
+            # Only add status (and etag if requested) if response is a hash
+            extra_fields = { status: status_code }
+            extra_fields[:etag] = etag if include_etag
+            response = response.merge(extra_fields) if response.is_a?(Hash)
             return response
           rescue JSON::ParserError
             # Handle case when response isn't valid JSON
-            return { error: 'Invalid JSON response', body: res.body, status: res.code.to_i }
+            error_response = { error: 'Invalid JSON response', body: res.body, status: status_code }
+            error_response[:etag] = etag if include_etag
+            return error_response
           end
         end
       rescue Timeout::Error,
@@ -921,5 +970,9 @@ module PostHog
       end
     end
     # rubocop:enable Lint/ShadowedException
+
+    def _mask_tokens_in_url(url)
+      url.gsub(/token=([^&]{10})[^&]*/, 'token=\1...')
+    end
   end
 end

data/lib/posthog/version.rb

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

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: posthog-ruby
 version: !ruby/object:Gem::Version
-  version: 3.3.2
+  version: 3.4.0
 platform: ruby
 authors:
 - ''
-autorequire: 
 bindir: bin
 cert_chain: []
-date: 2025-09-26 00:00:00.000000000 Z
+date: 2025-12-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: concurrent-ruby
@@ -57,7 +56,6 @@ licenses:
 - MIT
 metadata:
   rubygems_mfa_required: 'true'
-post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
@@ -72,8 +70,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.3.1
-signing_key: 
+rubygems_version: 3.6.6
 specification_version: 4
 summary: PostHog library
 test_files: []