From 9a144314a58278a084fcc53a4194abe30c0433ed Mon Sep 17 00:00:00 2001 From: Manoel Aranda Neto Date: Thu, 19 Nov 2026 10:23:13 +0100 Subject: [PATCH 1/6] feat(flags): support known-absent property keys in local evaluation --- .../flags-known-absent-property-keys.md | 5 + lib/posthog/client.rb | 115 +++++- lib/posthog/feature_flags.rb | 109 +++-- lib/posthog/known_absent_property_keys.rb | 87 ++++ lib/posthog/send_feature_flags_options.rb | 30 +- public_api_snapshot.txt | 16 +- .../feature_flags_known_absent_spec.rb | 377 ++++++++++++++++++ .../send_feature_flags_options_spec.rb | 14 + 8 files changed, 691 insertions(+), 62 deletions(-) create mode 100644 .changeset/flags-known-absent-property-keys.md create mode 100644 lib/posthog/known_absent_property_keys.rb create mode 100644 spec/posthog/feature_flags_known_absent_spec.rb diff --git a/.changeset/flags-known-absent-property-keys.md b/.changeset/flags-known-absent-property-keys.md new file mode 100644 index 00000000..2d871a31 --- /dev/null +++ b/.changeset/flags-known-absent-property-keys.md @@ -0,0 +1,5 @@ +--- +"posthog-ruby": minor +--- + +Add `person_property_keys_known_absent:` and `group_property_keys_known_absent:` to flag evaluation methods and `SendFeatureFlagsOptions`. A listed key is treated as absent during local evaluation, even when a value for it is passed, so `is_not_set` and the negated operators match and other operators don't, without a remote request. Fallback `/flags` requests carry the same keys. Each list allows at most 1000 keys, per group type for groups. A longer list raises `ArgumentError`. diff --git a/lib/posthog/client.rb b/lib/posthog/client.rb index 091e5f74..a7c79636 100644 --- a/lib/posthog/client.rb +++ b/lib/posthog/client.rb @@ -397,7 +397,9 @@ def capture(attrs) attrs[:groups] || {}, options ? options.person_properties : {}, options ? options.group_properties : {}, - options ? options.only_evaluate_locally : false + options ? options.only_evaluate_locally : false, + known_absent: KnownAbsentPropertyKeys.build(options&.person_property_keys_known_absent, + options&.group_property_keys_known_absent) ) when SendFeatureFlagsOptions # SendFeatureFlagsOptions object @@ -406,7 +408,11 @@ def capture(attrs) attrs[:groups] || {}, send_feature_flags_param.person_properties, send_feature_flags_param.group_properties, - send_feature_flags_param.only_evaluate_locally || false + send_feature_flags_param.only_evaluate_locally || false, + known_absent: KnownAbsentPropertyKeys.build( + send_feature_flags_param.person_property_keys_known_absent, + send_feature_flags_param.group_property_keys_known_absent + ) ) else # Invalid type, treat as false @@ -535,6 +541,10 @@ def queued_messages # @param person_properties [Hash] Properties to use when evaluating the user locally or remotely. # @param group_properties [Hash] Properties to use when evaluating groups locally or remotely. # @param only_evaluate_locally [Boolean] Skip the remote /flags call. + # @param person_property_keys_known_absent [Array, nil] Person property keys known to be + # absent. See {#evaluate_flags}. + # @param group_property_keys_known_absent [Hash{String, Symbol => Array}, nil] Group property + # keys known to be absent, by group type. See {#evaluate_flags}. # @param send_feature_flag_events [Boolean] Whether to capture `$feature_flag_called` for this access. # @return [Boolean, nil] Whether the flag is enabled, or nil when the flag could not be evaluated. # TODO: In future version, rename to `feature_flag_enabled?` @@ -545,7 +555,9 @@ def is_feature_enabled( # rubocop:disable Naming/PredicatePrefix person_properties: {}, group_properties: {}, only_evaluate_locally: false, - send_feature_flag_events: true + send_feature_flag_events: true, + person_property_keys_known_absent: nil, + group_property_keys_known_absent: nil ) _emit_deprecation( :is_feature_enabled, @@ -558,7 +570,9 @@ def is_feature_enabled( # rubocop:disable Naming/PredicatePrefix result = _get_feature_flag_result( flag_key, distinct_id, groups: groups, person_properties: person_properties, group_properties: group_properties, - only_evaluate_locally: only_evaluate_locally, send_feature_flag_events: send_feature_flag_events + only_evaluate_locally: only_evaluate_locally, send_feature_flag_events: send_feature_flag_events, + person_property_keys_known_absent: person_property_keys_known_absent, + group_property_keys_known_absent: group_property_keys_known_absent ) response = result&.value return nil if response.nil? @@ -582,6 +596,10 @@ def get_remote_config_payload(flag_key) # @param [Hash] person_properties key-value pairs of properties to associate with the user. # @param [Hash] group_properties # @param only_evaluate_locally [Boolean] Skip the remote /flags call. + # @param person_property_keys_known_absent [Array, nil] Person property keys known to be + # absent. See {#evaluate_flags}. + # @param group_property_keys_known_absent [Hash{String, Symbol => Array}, nil] Group property + # keys known to be absent, by group type. See {#evaluate_flags}. # @param send_feature_flag_events [Boolean] Whether to capture `$feature_flag_called` for this access. # # @return [String, Boolean, nil] The value of the feature flag @@ -605,7 +623,9 @@ def get_feature_flag( person_properties: {}, group_properties: {}, only_evaluate_locally: false, - send_feature_flag_events: true + send_feature_flag_events: true, + person_property_keys_known_absent: nil, + group_property_keys_known_absent: nil ) _emit_deprecation( :get_feature_flag, @@ -617,7 +637,9 @@ def get_feature_flag( result = _get_feature_flag_result( key, distinct_id, groups: groups, person_properties: person_properties, group_properties: group_properties, - only_evaluate_locally: only_evaluate_locally, send_feature_flag_events: send_feature_flag_events + only_evaluate_locally: only_evaluate_locally, send_feature_flag_events: send_feature_flag_events, + person_property_keys_known_absent: person_property_keys_known_absent, + group_property_keys_known_absent: group_property_keys_known_absent ) result&.value end @@ -630,6 +652,10 @@ def get_feature_flag( # @param person_properties [Hash] Properties to use when evaluating the user locally or remotely. # @param group_properties [Hash] Properties to use when evaluating groups locally or remotely. # @param only_evaluate_locally [Boolean] Skip the remote /flags call. + # @param person_property_keys_known_absent [Array, nil] Person property keys known to be + # absent. See {#evaluate_flags}. + # @param group_property_keys_known_absent [Hash{String, Symbol => Array}, nil] Group property + # keys known to be absent, by group type. See {#evaluate_flags}. # @param send_feature_flag_events [Boolean] Whether to capture `$feature_flag_called` for this access. # @return [PostHog::FeatureFlagResult, nil] def get_feature_flag_result( @@ -639,7 +665,9 @@ def get_feature_flag_result( person_properties: {}, group_properties: {}, only_evaluate_locally: false, - send_feature_flag_events: true + send_feature_flag_events: true, + person_property_keys_known_absent: nil, + group_property_keys_known_absent: nil ) _emit_deprecation( :get_feature_flag_result, @@ -653,7 +681,9 @@ def get_feature_flag_result( _get_feature_flag_result( key, distinct_id, groups: groups, person_properties: person_properties, group_properties: group_properties, - only_evaluate_locally: only_evaluate_locally, send_feature_flag_events: send_feature_flag_events + only_evaluate_locally: only_evaluate_locally, send_feature_flag_events: send_feature_flag_events, + person_property_keys_known_absent: person_property_keys_known_absent, + group_property_keys_known_absent: group_property_keys_known_absent ) end @@ -676,6 +706,16 @@ def get_feature_flag_result( # @param [Array, nil] flag_keys When set, scopes evaluation to only these flag keys. # An empty array returns an empty snapshot without evaluating flags; +nil+ evaluates all flags. # Distinct from {FeatureFlagEvaluations#only}, which filters the already-fetched snapshot in memory. + # @param [Array, nil] person_property_keys_known_absent Person property keys the caller knows + # are absent for this evaluation. A listed key is absent even when +person_properties+ has a value for it, + # so local evaluation resolves it definitively: +is_not_set+ and the negated operators (+is_not+, + # +not_icontains+, +not_starts_with+, +not_ends_with+, +not_regex+) match, and every other operator + # doesn't. Keys starting with +__posthog_person_metadata__+ are ignored. Sent to +/flags+ on remote + # evaluation. At most 1000 keys, counting duplicates; a longer list raises +ArgumentError+ and is never + # truncated. + # @param [Hash{String, Symbol => Array}, nil] group_property_keys_known_absent Group property + # keys known to be absent, by group type name. Each group type's keys apply only to that group type and + # follow the same rules and 1000-key limit as +person_property_keys_known_absent+. # @return [PostHog::FeatureFlagEvaluations] def evaluate_flags( distinct_id, @@ -684,7 +724,9 @@ def evaluate_flags( group_properties: {}, only_evaluate_locally: false, disable_geoip: nil, - flag_keys: nil + flag_keys: nil, + person_property_keys_known_absent: nil, + group_property_keys_known_absent: nil ) host = _feature_flag_evaluations_host @@ -700,6 +742,8 @@ def evaluate_flags( ) end + known_absent = KnownAbsentPropertyKeys.build(person_property_keys_known_absent, + group_property_keys_known_absent) groups, person_properties, group_properties = add_local_person_and_group_properties( groups, person_properties, group_properties ) @@ -719,7 +763,8 @@ def evaluate_flags( begin match = @feature_flags_poller.send( :_compute_flag_locally, - definition, distinct_id, groups, person_properties, group_properties, snapshot: definition_snapshot + definition, distinct_id, groups, person_properties, group_properties, + snapshot: definition_snapshot, known_absent: known_absent ) rescue PostHog::RequiresServerEvaluation, PostHog::InconclusiveMatchError => e unresolved_flags[key.to_s] = e.reason @@ -770,7 +815,8 @@ def evaluate_flags( minimal_flag_called_events = false begin flags_response = @feature_flags_poller.get_flags( - distinct_id, groups, person_properties, group_properties, flag_keys, disable_geoip + distinct_id, groups, person_properties, group_properties, flag_keys, disable_geoip, + known_absent: known_absent ) minimal_flag_called_events = flags_response[:minimalFlagCalledEvents] == true request_id = flags_response[:requestId] @@ -827,6 +873,10 @@ def evaluate_flags( # @param [Hash] person_properties key-value pairs of properties to associate with the user. # @param [Hash] group_properties # @param only_evaluate_locally [Boolean] Skip the remote /flags call. + # @param person_property_keys_known_absent [Array, nil] Person property keys known to be + # absent. See {#evaluate_flags}. + # @param group_property_keys_known_absent [Hash{String, Symbol => Array}, nil] Group property + # keys known to be absent, by group type. See {#evaluate_flags}. # # @return [Hash] String (not symbol) key value pairs of flag and their values def get_all_flags( @@ -834,15 +884,19 @@ def get_all_flags( groups: {}, person_properties: {}, group_properties: {}, - only_evaluate_locally: false + only_evaluate_locally: false, + person_property_keys_known_absent: nil, + group_property_keys_known_absent: nil ) return {} if @disabled + known_absent = KnownAbsentPropertyKeys.build(person_property_keys_known_absent, + group_property_keys_known_absent) groups, person_properties, group_properties = add_local_person_and_group_properties( groups, person_properties, group_properties ) @feature_flags_poller.get_all_flags(distinct_id, groups, person_properties, group_properties, - only_evaluate_locally) + only_evaluate_locally, known_absent: known_absent) end # Returns payload for a given feature flag @@ -857,6 +911,10 @@ def get_all_flags( # @param person_properties [Hash] key-value pairs of properties to associate with the user. # @param group_properties [Hash] # @param only_evaluate_locally [Boolean] + # @param person_property_keys_known_absent [Array, nil] Person property keys known to be + # absent. See {#evaluate_flags}. + # @param group_property_keys_known_absent [Hash{String, Symbol => Array}, nil] Group property + # keys known to be absent, by group type. See {#evaluate_flags}. # @return [Object, nil] The parsed payload for the matched flag value. # # @deprecated Use {#evaluate_flags} and {FeatureFlagEvaluations#get_flag_payload} instead. @@ -867,7 +925,9 @@ def get_feature_flag_payload( groups: {}, person_properties: {}, group_properties: {}, - only_evaluate_locally: false + only_evaluate_locally: false, + person_property_keys_known_absent: nil, + group_property_keys_known_absent: nil ) _emit_deprecation( :get_feature_flag_payload, @@ -879,11 +939,14 @@ def get_feature_flag_payload( return nil if @disabled key = key.to_s + known_absent = KnownAbsentPropertyKeys.build(person_property_keys_known_absent, + group_property_keys_known_absent) groups, person_properties, group_properties = add_local_person_and_group_properties( groups, person_properties, group_properties ) @feature_flags_poller.get_feature_flag_payload(key, distinct_id, match_value, groups, person_properties, - group_properties, only_evaluate_locally) + group_properties, only_evaluate_locally, + known_absent: known_absent) end # Returns all flags and payloads for a given user @@ -897,21 +960,30 @@ def get_feature_flag_payload( # @param person_properties [Hash] key-value pairs of properties to associate with the user. # @param group_properties [Hash] # @param only_evaluate_locally [Boolean] Skip the remote /flags call. + # @param person_property_keys_known_absent [Array, nil] Person property keys known to be + # absent. See {#evaluate_flags}. + # @param group_property_keys_known_absent [Hash{String, Symbol => Array}, nil] Group property + # keys known to be absent, by group type. See {#evaluate_flags}. # def get_all_flags_and_payloads( distinct_id, groups: {}, person_properties: {}, group_properties: {}, - only_evaluate_locally: false + only_evaluate_locally: false, + person_property_keys_known_absent: nil, + group_property_keys_known_absent: nil ) return { featureFlags: {}, featureFlagPayloads: {} } if @disabled + known_absent = KnownAbsentPropertyKeys.build(person_property_keys_known_absent, + group_property_keys_known_absent) groups, person_properties, group_properties = add_local_person_and_group_properties( groups, person_properties, group_properties ) response = @feature_flags_poller.get_all_flags_and_payloads( - distinct_id, groups, person_properties, group_properties, only_evaluate_locally + distinct_id, groups, person_properties, group_properties, only_evaluate_locally, + known_absent: known_absent ) # Remove internal information @@ -1154,18 +1226,23 @@ def _get_feature_flag_result( person_properties: {}, group_properties: {}, only_evaluate_locally: false, - send_feature_flag_events: true + send_feature_flag_events: true, + person_property_keys_known_absent: nil, + group_property_keys_known_absent: nil ) return nil if @disabled key = key.to_s + known_absent = KnownAbsentPropertyKeys.build(person_property_keys_known_absent, + group_property_keys_known_absent) groups, person_properties, group_properties = add_local_person_and_group_properties( groups, person_properties, group_properties ) feature_flag_response, flag_was_locally_evaluated, request_id, evaluated_at, feature_flag_error, payload, has_experiment, minimal_flag_called_events = @feature_flags_poller.get_feature_flag( - key, distinct_id, groups, person_properties, group_properties, only_evaluate_locally + key, distinct_id, groups, person_properties, group_properties, only_evaluate_locally, + known_absent: known_absent ) if send_feature_flag_events properties = { diff --git a/lib/posthog/feature_flags.rb b/lib/posthog/feature_flags.rb index 64475061..63ec19c2 100644 --- a/lib/posthog/feature_flags.rb +++ b/lib/posthog/feature_flags.rb @@ -11,6 +11,7 @@ require 'posthog/flag_definition_cache' require 'posthog/unresolved_flag_reason' require 'posthog/flag_evaluation_errors' +require 'posthog/known_absent_property_keys' require 'digest' require 'set' @@ -148,7 +149,8 @@ def get_feature_variants( person_properties = {}, group_properties = {}, only_evaluate_locally = false, - raise_on_error = false + raise_on_error = false, + known_absent: nil ) groups, person_properties, group_properties = normalize_flag_evaluation_inputs( groups, person_properties, group_properties @@ -160,7 +162,8 @@ def get_feature_variants( person_properties, group_properties, only_evaluate_locally, - raise_on_error + raise_on_error, + known_absent: known_absent ) if flags_data.key?(:featureFlags) @@ -176,13 +179,15 @@ def get_feature_payloads( groups = {}, person_properties = {}, group_properties = {}, - _only_evaluate_locally = false + _only_evaluate_locally = false, + known_absent: nil ) flags_data = get_all_flags_and_payloads( distinct_id, groups, person_properties, - group_properties + group_properties, + known_absent: known_absent ) if flags_data.key?(:featureFlagPayloads) @@ -194,7 +199,7 @@ def get_feature_payloads( end def get_flags(distinct_id, groups = {}, person_properties = {}, group_properties = {}, flag_keys = nil, - disable_geoip = nil) + disable_geoip = nil, known_absent: nil) flag_keys = flag_keys.map(&:to_s) if flag_keys.is_a?(Array) request_data = { distinct_id: distinct_id, @@ -202,6 +207,7 @@ def get_flags(distinct_id, groups = {}, person_properties = {}, group_properties person_properties: person_properties, group_properties: group_properties } + request_data.merge!(known_absent.request_fields) if known_absent request_data[:flag_keys_to_evaluate] = flag_keys if flag_keys && !flag_keys.empty? # The flags endpoint treats an omitted/null value as false; serialize that same default explicitly. request_data[:geoip_disable] = disable_geoip.nil? ? false : disable_geoip @@ -242,7 +248,8 @@ def get_feature_flag( person_properties = {}, group_properties = {}, only_evaluate_locally = false, - snapshot: nil + snapshot: nil, + known_absent: nil ) key = key.to_s @@ -257,7 +264,7 @@ def get_feature_flag( unless feature_flag.nil? begin response = _compute_flag_locally(feature_flag, distinct_id, groups, person_properties, group_properties, - snapshot: snapshot) + snapshot: snapshot, known_absent: known_absent) payload = _compute_flag_payload_locally(key, response, snapshot: snapshot) unless response.nil? logger.debug "Successfully computed flag locally: #{key} -> #{response}" rescue RequiresServerEvaluation, InconclusiveMatchError => e @@ -287,7 +294,7 @@ def get_feature_flag( begin errors = [] flags_data = get_all_flags_and_payloads(distinct_id, groups, person_properties, group_properties, - only_evaluate_locally, true) + only_evaluate_locally, true, known_absent: known_absent) if flags_data.key?(:featureFlags) flags = stringify_keys(flags_data[:featureFlags] || {}) payloads = stringify_keys(flags_data[:featureFlagPayloads] || {}) @@ -341,7 +348,8 @@ def get_all_flags( groups = {}, person_properties = {}, group_properties = {}, - only_evaluate_locally = false + only_evaluate_locally = false, + known_absent: nil ) if @quota_limited.true? logger.debug 'Not fetching flags from server - quota limited' @@ -354,7 +362,8 @@ def get_all_flags( groups, person_properties, group_properties, - only_evaluate_locally + only_evaluate_locally, + known_absent: known_absent ) response[:featureFlags] @@ -366,7 +375,8 @@ def get_all_flags_and_payloads( person_properties = {}, group_properties = {}, only_evaluate_locally = false, - raise_on_error = false + raise_on_error = false, + known_absent: nil ) load_feature_flags snapshot = _evaluation_snapshot @@ -379,7 +389,7 @@ def get_all_flags_and_payloads( snapshot[:flags].each do |flag| match_value = _compute_flag_locally(flag, distinct_id, groups, person_properties, group_properties, - snapshot: snapshot) + snapshot: snapshot, known_absent: known_absent) flags[flag[:key]] = match_value match_payload = _compute_flag_payload_locally(flag[:key], match_value, snapshot: snapshot) payloads[flag[:key]] = match_payload if match_payload @@ -398,7 +408,8 @@ def get_all_flags_and_payloads( if fallback_to_server && !only_evaluate_locally begin - flags_and_payloads = get_flags(distinct_id, groups, person_properties, group_properties) + flags_and_payloads = get_flags(distinct_id, groups, person_properties, group_properties, + known_absent: known_absent) flag_details = flags_and_payloads[:flags] errors_while_computing = flags_and_payloads[:errorsWhileComputingFlags] || false quota_limited = flags_and_payloads[:quotaLimited] @@ -461,7 +472,8 @@ def get_feature_flag_payload( groups = {}, person_properties = {}, group_properties = {}, - only_evaluate_locally = false + only_evaluate_locally = false, + known_absent: nil ) key = key.to_s load_feature_flags @@ -475,13 +487,15 @@ def get_feature_flag_payload( person_properties, group_properties, true, - snapshot: snapshot + snapshot: snapshot, + known_absent: known_absent )[0] end response = nil response = _compute_flag_payload_locally(key, match_value, snapshot: snapshot) unless match_value.nil? if response.nil? && !only_evaluate_locally - flags_payloads = get_feature_payloads(distinct_id, groups, person_properties, group_properties) + flags_payloads = get_feature_payloads(distinct_id, groups, person_properties, group_properties, + known_absent: known_absent) response = flags_payloads[key.downcase] || nil end response @@ -759,13 +773,24 @@ def self.exact_property_match?(filter, value, property_matching_version) private_class_method :boolean_like?, :legacy_truthy?, :sorted_composite, :property_string, :exact_property_match? - def self.match_property(property, property_values, cohort_properties = {}, property_matching_version: 1) + # @param known_absent_keys [Set, nil] Keys of property_values known to be absent. A listed key + # resolves definitively by operator, even when property_values has a value for it. + def self.match_property(property, property_values, cohort_properties = {}, property_matching_version: 1, + known_absent_keys: nil) # only looks for matches where key exists in property_values # Handle cohort properties if extract_value(property, :type) == 'cohort' return match_cohort(property, property_values, cohort_properties, - property_matching_version: property_matching_version) + property_matching_version: property_matching_version, + known_absent_keys: known_absent_keys) + end + + if known_absent_keys&.include?((property[:key] || property['key']).to_s) + # An unsupported operator or malformed filter stays inconclusive, so it still falls back to the server. + assert_filter_supported(property) + operator = property[:operator] || property['operator'] || 'exact' + return KnownAbsentPropertyKeys::MATCHING_OPERATORS.include?(operator) end begin @@ -1071,7 +1096,8 @@ def self.regex_repetition_end(characters, index) end private_class_method :regex_repetition_end - def self.match_cohort(property, property_values, cohort_properties, property_matching_version: 1) + def self.match_cohort(property, property_values, cohort_properties, property_matching_version: 1, + known_absent_keys: nil) # Cohort properties are in the form of property groups like this: # { # "cohort_id" => { @@ -1092,10 +1118,12 @@ def self.match_cohort(property, property_values, cohort_properties, property_mat end match_property_group(property_group, property_values, cohort_properties, - property_matching_version: property_matching_version) + property_matching_version: property_matching_version, + known_absent_keys: known_absent_keys) end - def self.match_property_group(property_group, property_values, cohort_properties, property_matching_version: 1) + def self.match_property_group(property_group, property_values, cohort_properties, property_matching_version: 1, + known_absent_keys: nil) return true if property_group.nil? || property_group.empty? group_type = extract_value(property_group, :type) @@ -1106,12 +1134,14 @@ def self.match_property_group(property_group, property_values, cohort_properties if nested_property_group?(properties) property_group_items_match?(properties, group_type) do |group| match_property_group(group, property_values, cohort_properties, - property_matching_version: property_matching_version) + property_matching_version: property_matching_version, + known_absent_keys: known_absent_keys) end else property_group_items_match?(properties, group_type) do |prop| matches = match_property(prop, property_values, cohort_properties, - property_matching_version: property_matching_version) + property_matching_version: property_matching_version, + known_absent_keys: known_absent_keys) extract_value(prop, :negation) ? !matches : matches end end @@ -1174,9 +1204,10 @@ def self.property_group_items_match?(items, group_type) # @param distinct_id [String] The distinct ID being evaluated # @param properties [Hash] Person properties for evaluation # @param cohort_properties [Hash] Cohort properties for evaluation + # @param known_absent_keys [Set, nil] Keys of properties known to be absent # @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, - snapshot: _evaluation_snapshot) + snapshot: _evaluation_snapshot, known_absent: nil, known_absent_keys: nil) if snapshot[:flags_by_key].nil? || evaluation_cache.nil? # Cannot evaluate flag dependencies without required context raise InconclusiveMatchError.new( @@ -1218,7 +1249,9 @@ def evaluate_flag_dependency(property, evaluation_cache, distinct_id, properties properties, evaluation_cache, cohort_properties, - snapshot: snapshot + snapshot: snapshot, + known_absent: known_absent, + known_absent_keys: known_absent_keys ) evaluation_cache[dep_flag_key] = dep_result rescue RequiresServerEvaluation => e @@ -1384,7 +1417,7 @@ def _evaluation_snapshot end def _compute_flag_locally(flag, distinct_id, groups = {}, person_properties = {}, group_properties = {}, - snapshot: _evaluation_snapshot) + snapshot: _evaluation_snapshot, known_absent: nil) # An inactive flag is false whatever its experience continuity setting. return false unless flag[:active] @@ -1407,7 +1440,8 @@ def _compute_flag_locally(flag, distinct_id, groups = {}, person_properties = {} return match_feature_flag_properties(flag, distinct_id, local_person_properties, evaluation_cache, snapshot[:cohorts], groups: groups, group_properties: group_properties, - snapshot: snapshot) + snapshot: snapshot, known_absent: known_absent, + known_absent_keys: known_absent&.person_keys) end group_name = snapshot[:group_type_mapping][aggregation_group_type_index.to_s.to_sym] @@ -1433,7 +1467,8 @@ def _compute_flag_locally(flag, distinct_id, groups = {}, person_properties = {} focused_group_properties = group_properties[group_name_symbol] match_feature_flag_properties(flag, groups[group_name_symbol], focused_group_properties, evaluation_cache, snapshot[:cohorts], groups: groups, group_properties: group_properties, - snapshot: snapshot) + snapshot: snapshot, known_absent: known_absent, + known_absent_keys: known_absent&.group_keys(group_name)) end def _compute_flag_payload_locally(key, match_value, snapshot: _evaluation_snapshot) @@ -1449,8 +1484,11 @@ def _compute_flag_payload_locally(key, match_value, snapshot: _evaluation_snapsh response end + # known_absent_keys are the listed keys for `properties`; known_absent holds every listing, so a + # condition aggregated by another group type can use that group type's keys. def match_feature_flag_properties(flag, distinct_id, properties, evaluation_cache, cohort_properties = {}, - groups: {}, group_properties: {}, snapshot: _evaluation_snapshot) + groups: {}, group_properties: {}, snapshot: _evaluation_snapshot, + known_absent: nil, known_absent_keys: nil) flag_filters = flag[:filters] || {} # Holdouts precede release conditions: a held-out identifier is excluded from @@ -1475,6 +1513,7 @@ def match_feature_flag_properties(flag, distinct_id, properties, evaluation_cach effective_properties = properties effective_bucketing = distinct_id + effective_known_absent_keys = known_absent_keys # Mixed-override path: condition-level aggregation differs from flag-level. # This assumes flag-level aggregation is nil for mixed flags. @@ -1498,11 +1537,13 @@ def match_feature_flag_properties(flag, distinct_id, properties, evaluation_cach end effective_properties = group_properties[group_name.to_sym] effective_bucketing = groups[group_name.to_sym] + effective_known_absent_keys = known_absent&.group_keys(group_name) end end case condition_match_outcome(flag, effective_bucketing, condition, effective_properties, evaluation_cache, - cohort_properties, snapshot: snapshot) + cohort_properties, snapshot: snapshot, known_absent: known_absent, + known_absent_keys: effective_known_absent_keys) when :match variant_override = condition[:variant] flag_multivariate = flag_filters[:multivariate] || {} @@ -1563,7 +1604,7 @@ def condition_match(flag, distinct_id, condition, properties, evaluation_cache, # Distinguishing :no_match from :out_of_rollout_bound lets the caller implement the # early_exit behavior (mirrors the server-side Rust evaluation engine). def condition_match_outcome(flag, distinct_id, condition, properties, evaluation_cache, cohort_properties = {}, - snapshot: _evaluation_snapshot) + snapshot: _evaluation_snapshot, known_absent: nil, known_absent_keys: nil) rollout_percentage = condition[:rollout_percentage] unless (condition[:properties] || []).empty? @@ -1575,10 +1616,12 @@ def condition_match_outcome(flag, distinct_id, condition, properties, evaluation matches = if prop[:type] == 'flag' evaluate_flag_dependency(prop, evaluation_cache, distinct_id, properties, cohort_properties, - snapshot: snapshot) + snapshot: snapshot, known_absent: known_absent, + known_absent_keys: known_absent_keys) else FeatureFlagsPoller.match_property(prop, properties, cohort_properties, - property_matching_version: snapshot[:property_matching_version]) + property_matching_version: snapshot[:property_matching_version], + known_absent_keys: known_absent_keys) end return :no_match unless matches rescue RequiresServerEvaluation => e diff --git a/lib/posthog/known_absent_property_keys.rb b/lib/posthog/known_absent_property_keys.rb new file mode 100644 index 00000000..fc718035 --- /dev/null +++ b/lib/posthog/known_absent_property_keys.rb @@ -0,0 +1,87 @@ +# frozen_string_literal: true + +require 'set' + +module PostHog + # Person and group property keys the caller knows are absent for one flag evaluation. + # + # @api private + class KnownAbsentPropertyKeys + # The flags service rejects a longer list, counting duplicates, per group type for groups. + MAX_KEYS = 1000 + PERSON_FIELD = 'person_property_keys_known_absent' + GROUP_FIELD = 'group_property_keys_known_absent' + # Persons-table fields such as `created_at` use this prefix and are never hidden by known absence. + PERSON_METADATA_PREFIX = '__posthog_person_metadata__' + # A listed key matches these operators and no others. + MATCHING_OPERATORS = %w[is_not_set is_not not_icontains not_starts_with not_ends_with not_regex].freeze + + # @return [Set] Listed person keys used for local matching. + attr_reader :person_keys + + # Validates and normalizes the public inputs. + # + # @param person_property_keys_known_absent [Array, Set, nil] + # @param group_property_keys_known_absent [Hash{String, Symbol => Array}, nil] + # @return [PostHog::KnownAbsentPropertyKeys, nil] nil when neither input was provided. + # @raise [ArgumentError] when an input has the wrong type or a list holds more than {MAX_KEYS} keys. + def self.build(person_property_keys_known_absent, group_property_keys_known_absent) + return nil if person_property_keys_known_absent.nil? && group_property_keys_known_absent.nil? + + person = if person_property_keys_known_absent.nil? + [] + else + validate_keys(person_property_keys_known_absent, PERSON_FIELD) + end + + groups = {} + unless group_property_keys_known_absent.nil? + unless group_property_keys_known_absent.is_a?(Hash) + raise ArgumentError, "#{GROUP_FIELD} must be a Hash of group type to property keys" + end + + group_property_keys_known_absent.each do |group_type, keys| + groups[group_type.to_s] = validate_keys(keys, "#{GROUP_FIELD}[#{group_type}]") + end + end + + new(person, groups) + end + + def self.validate_keys(keys, field) + raise ArgumentError, "#{field} must be an Array of property keys" unless keys.is_a?(Array) || keys.is_a?(Set) + raise ArgumentError, "#{field} allows at most #{MAX_KEYS} keys, got #{keys.size}" if keys.size > MAX_KEYS + + keys.map do |key| + unless key.is_a?(String) || key.is_a?(Symbol) + raise ArgumentError, "#{field} must contain only String or Symbol keys" + end + + key.to_s + end + end + private_class_method :validate_keys + + def initialize(person, groups) + @person = person + @groups = groups + @person_keys = person.reject { |key| key.start_with?(PERSON_METADATA_PREFIX) }.to_set.freeze + @group_keys = groups.to_h { |group_type, keys| [group_type, keys.to_set.freeze] }.freeze + end + + # @param group_type [String, Symbol] + # @return [Set, nil] Listed keys for that group type only. + def group_keys(group_type) + @group_keys[group_type.to_s] + end + + # @return [Hash] The `/flags` request body fields, omitting a field with nothing listed. + def request_fields + fields = {} + fields[PERSON_FIELD.to_sym] = @person unless @person.empty? + groups = @groups.reject { |_group_type, keys| keys.empty? } + fields[GROUP_FIELD.to_sym] = groups unless groups.empty? + fields + end + end +end diff --git a/lib/posthog/send_feature_flags_options.rb b/lib/posthog/send_feature_flags_options.rb index c94d37fd..83d086a0 100644 --- a/lib/posthog/send_feature_flags_options.rb +++ b/lib/posthog/send_feature_flags_options.rb @@ -16,22 +16,42 @@ class SendFeatureFlagsOptions # @return [Hash] Group properties to use for feature flag evaluation. attr_reader :group_properties + # @return [Array, nil] Person property keys known to be absent. + attr_reader :person_property_keys_known_absent + + # @return [Hash{String, Symbol => Array}, nil] Group property keys known to be absent, + # by group type. + attr_reader :group_property_keys_known_absent + # @param only_evaluate_locally [Boolean, nil] Skip remote feature flag evaluation. # @param person_properties [Hash, nil] Person properties to use for feature flag evaluation. # @param group_properties [Hash, nil] Group properties to use for feature flag evaluation. - def initialize(only_evaluate_locally: nil, person_properties: nil, group_properties: nil) + # @param person_property_keys_known_absent [Array, nil] Person property keys known to be absent. + # @param group_property_keys_known_absent [Hash{String, Symbol => Array}, nil] Group property + # keys known to be absent, by group type. + def initialize(only_evaluate_locally: nil, person_properties: nil, group_properties: nil, + person_property_keys_known_absent: nil, group_property_keys_known_absent: nil) @only_evaluate_locally = only_evaluate_locally @person_properties = person_properties || {} @group_properties = group_properties || {} + @person_property_keys_known_absent = person_property_keys_known_absent + @group_property_keys_known_absent = group_property_keys_known_absent end # @return [Hash] A hash representation suitable for `capture(send_feature_flags:)`. def to_h - { + hash = { only_evaluate_locally: @only_evaluate_locally, person_properties: @person_properties, group_properties: @group_properties } + unless @person_property_keys_known_absent.nil? + hash[:person_property_keys_known_absent] = @person_property_keys_known_absent + end + unless @group_property_keys_known_absent.nil? + hash[:group_property_keys_known_absent] = @group_property_keys_known_absent + end + hash end # @param hash [Hash] @@ -42,7 +62,11 @@ def self.from_hash(hash) new( only_evaluate_locally: PostHog::Utils.get_by_symbol_or_string_key(hash, :only_evaluate_locally), person_properties: PostHog::Utils.get_by_symbol_or_string_key(hash, :person_properties), - group_properties: PostHog::Utils.get_by_symbol_or_string_key(hash, :group_properties) + group_properties: PostHog::Utils.get_by_symbol_or_string_key(hash, :group_properties), + person_property_keys_known_absent: + PostHog::Utils.get_by_symbol_or_string_key(hash, :person_property_keys_known_absent), + group_property_keys_known_absent: + PostHog::Utils.get_by_symbol_or_string_key(hash, :group_property_keys_known_absent) ) end end diff --git a/public_api_snapshot.txt b/public_api_snapshot.txt index ef26a486..b1a7a2aa 100644 --- a/public_api_snapshot.txt +++ b/public_api_snapshot.txt @@ -12,18 +12,18 @@ instance_method PostHog::Client#clear() instance_method PostHog::Client#dequeue_last_message() instance_method PostHog::Client#emails() instance_method PostHog::Client#enabled?() -instance_method PostHog::Client#evaluate_flags(distinct_id, groups: ..., person_properties: ..., group_properties: ..., only_evaluate_locally: ..., disable_geoip: ..., flag_keys: ...) +instance_method PostHog::Client#evaluate_flags(distinct_id, groups: ..., person_properties: ..., group_properties: ..., only_evaluate_locally: ..., disable_geoip: ..., flag_keys: ..., person_property_keys_known_absent: ..., group_property_keys_known_absent: ...) instance_method PostHog::Client#feature_flags_loaded?() instance_method PostHog::Client#flush(timeout: ...) -instance_method PostHog::Client#get_all_flags(distinct_id, groups: ..., person_properties: ..., group_properties: ..., only_evaluate_locally: ...) -instance_method PostHog::Client#get_all_flags_and_payloads(distinct_id, groups: ..., person_properties: ..., group_properties: ..., only_evaluate_locally: ...) -instance_method PostHog::Client#get_feature_flag(key, distinct_id, groups: ..., person_properties: ..., group_properties: ..., only_evaluate_locally: ..., send_feature_flag_events: ...) -instance_method PostHog::Client#get_feature_flag_payload(key, distinct_id, match_value: ..., groups: ..., person_properties: ..., group_properties: ..., only_evaluate_locally: ...) -instance_method PostHog::Client#get_feature_flag_result(key, distinct_id, groups: ..., person_properties: ..., group_properties: ..., only_evaluate_locally: ..., send_feature_flag_events: ...) +instance_method PostHog::Client#get_all_flags(distinct_id, groups: ..., person_properties: ..., group_properties: ..., only_evaluate_locally: ..., person_property_keys_known_absent: ..., group_property_keys_known_absent: ...) +instance_method PostHog::Client#get_all_flags_and_payloads(distinct_id, groups: ..., person_properties: ..., group_properties: ..., only_evaluate_locally: ..., person_property_keys_known_absent: ..., group_property_keys_known_absent: ...) +instance_method PostHog::Client#get_feature_flag(key, distinct_id, groups: ..., person_properties: ..., group_properties: ..., only_evaluate_locally: ..., send_feature_flag_events: ..., person_property_keys_known_absent: ..., group_property_keys_known_absent: ...) +instance_method PostHog::Client#get_feature_flag_payload(key, distinct_id, match_value: ..., groups: ..., person_properties: ..., group_properties: ..., only_evaluate_locally: ..., person_property_keys_known_absent: ..., group_property_keys_known_absent: ...) +instance_method PostHog::Client#get_feature_flag_result(key, distinct_id, groups: ..., person_properties: ..., group_properties: ..., only_evaluate_locally: ..., send_feature_flag_events: ..., person_property_keys_known_absent: ..., group_property_keys_known_absent: ...) instance_method PostHog::Client#get_remote_config_payload(flag_key) instance_method PostHog::Client#group_identify(attrs) instance_method PostHog::Client#identify(attrs) -instance_method PostHog::Client#is_feature_enabled(flag_key, distinct_id, groups: ..., person_properties: ..., group_properties: ..., only_evaluate_locally: ..., send_feature_flag_events: ...) +instance_method PostHog::Client#is_feature_enabled(flag_key, distinct_id, groups: ..., person_properties: ..., group_properties: ..., only_evaluate_locally: ..., send_feature_flag_events: ..., person_property_keys_known_absent: ..., group_property_keys_known_absent: ...) instance_method PostHog::Client#queued_messages() instance_method PostHog::Client#reload_feature_flags() instance_method PostHog::Client#shutdown(timeout: ...) @@ -331,8 +331,10 @@ class PostHog::RequiresServerEvaluation < StandardError instance_method PostHog::RequiresServerEvaluation#reason() class PostHog::SendFeatureFlagsOptions instance_method PostHog::SendFeatureFlagsOptions#group_properties() +instance_method PostHog::SendFeatureFlagsOptions#group_property_keys_known_absent() instance_method PostHog::SendFeatureFlagsOptions#only_evaluate_locally() instance_method PostHog::SendFeatureFlagsOptions#person_properties() +instance_method PostHog::SendFeatureFlagsOptions#person_property_keys_known_absent() instance_method PostHog::SendFeatureFlagsOptions#to_h() class_method PostHog::SendFeatureFlagsOptions.from_hash(hash) module PostHog::UnresolvedFlagReason diff --git a/spec/posthog/feature_flags_known_absent_spec.rb b/spec/posthog/feature_flags_known_absent_spec.rb new file mode 100644 index 00000000..00eaec20 --- /dev/null +++ b/spec/posthog/feature_flags_known_absent_spec.rb @@ -0,0 +1,377 @@ +# frozen_string_literal: true + +require 'spec_helper' + +module PostHog + describe 'known-absent property keys' do + let(:definitions_endpoint) { 'https://us.i.posthog.com/flags/definitions?token=testsecret&send_cohorts=true' } + let(:flags_endpoint) { 'https://us.i.posthog.com/flags/?v=2' } + let(:remote_response) do + { flags: { 'remote-flag' => { key: 'remote-flag', enabled: true, variant: nil, metadata: { id: 9 } } } } + end + + def flag(key, *properties, **extra) + { id: 1, key: key, active: true, filters: { groups: [{ properties: properties, rollout_percentage: 100 }] } } + .merge(extra) + end + + def person(key, operator, value = nil) + filter = { key: key, operator: operator, type: 'person' } + filter[:value] = value unless value.nil? + filter + end + + def local_client(*flags, cohorts: {}, group_type_mapping: {}) + stub_request(:get, definitions_endpoint).to_return( + status: 200, body: { flags: flags, cohorts: cohorts, group_type_mapping: group_type_mapping }.to_json + ) + stub_request(:post, flags_endpoint).to_return(status: 200, body: remote_response.to_json) + Client.new(api_key: API_KEY, personal_api_key: API_KEY, test_mode: true) + end + + def flags_request_body + body = nil + expect(WebMock).to(have_requested(:post, flags_endpoint).with { |request| body = JSON.parse(request.body) }) + body + end + + describe 'operator results for a listed key' do + { + ['is_not_set', nil] => true, + ['is_set', nil] => false, + %w[exact pro] => false, + %w[is_not pro] => true, + %w[icontains pro] => false, + %w[not_icontains pro] => true, + %w[starts_with pro] => false, + %w[not_starts_with pro] => true, + %w[ends_with pro] => false, + %w[not_ends_with pro] => true, + ['regex', '^pro'] => false, + ['not_regex', '^pro'] => true, + %w[gt 10] => false, + %w[gte 10] => false, + %w[lt 10] => false, + %w[lte 10] => false, + ['is_date_before', '2025-01-01T10:00:00Z'] => false, + ['is_date_after', '2025-01-01T10:00:00Z'] => false, + ['semver_eq', '1.2.3'] => false, + ['semver_neq', '1.2.3'] => false, + ['semver_gt', '1.2.3'] => false, + ['semver_gte', '1.2.3'] => false, + ['semver_lt', '1.2.3'] => false, + ['semver_lte', '1.2.3'] => false, + ['semver_tilde', '1.2.3'] => false, + ['semver_caret', '1.2.3'] => false, + ['semver_wildcard', '1.2.*'] => false + }.each do |(operator, value), expected| + it "#{expected ? 'matches' : 'does not match'} #{operator}" do + property = { key: 'plan', operator: operator, value: value } + expect(FeatureFlagsPoller.match_property(property, {}, known_absent_keys: Set['plan'])).to be(expected) + end + end + + it 'resolves the flag locally without a remote request' do + c = local_client(flag('incomplete', person('plan', 'is_not_set')), flag('complete', person('plan', 'is_set'))) + + snapshot = c.evaluate_flags('user-1', flag_keys: %w[incomplete complete], + person_property_keys_known_absent: ['plan']) + + expect(snapshot.get_flag('incomplete')).to be(true) + expect(snapshot.get_flag('complete')).to be(false) + expect(WebMock).not_to have_requested(:post, flags_endpoint) + end + end + + it 'overrides a supplied value for a listed key' do + c = local_client(flag('incomplete', person('plan', 'is_not_set'))) + + snapshot = c.evaluate_flags('user-1', flag_keys: ['incomplete'], person_properties: { plan: 'pro' }, + person_property_keys_known_absent: [:plan]) + + expect(snapshot.get_flag('incomplete')).to be(true) + expect(WebMock).not_to have_requested(:post, flags_endpoint) + end + + it 'overrides the distinct_id the SDK adds to person properties' do + c = local_client(flag('no-distinct-id', person('distinct_id', 'is_not_set'))) + + snapshot = c.evaluate_flags('user-1', flag_keys: ['no-distinct-id'], only_evaluate_locally: true, + person_property_keys_known_absent: ['distinct_id']) + + expect(snapshot.get_flag('no-distinct-id')).to be(true) + end + + it 'keeps an omitted key that is not listed inconclusive' do + c = local_client(flag('incomplete', person('plan', 'is_not_set'))) + + snapshot = c.evaluate_flags('user-1', flag_keys: ['incomplete'], only_evaluate_locally: true, + person_property_keys_known_absent: ['region']) + + expect(snapshot.unresolved_flags).to eq('incomplete' => UnresolvedFlagReason::MISSING_CONTEXT) + end + + it 'ignores person keys with the person-metadata prefix' do + key = '__posthog_person_metadata__created_at' + c = local_client(flag('old-account', person(key, 'is_date_before', '2025-01-01T00:00:00Z'))) + + snapshot = c.evaluate_flags('user-1', flag_keys: ['old-account'], only_evaluate_locally: true, + person_properties: { key => '2024-01-01T00:00:00Z' }, + person_property_keys_known_absent: [key]) + + expect(snapshot.get_flag('old-account')).to be(true) + end + + it 'still sends a person-metadata key to /flags as provided' do + known_absent = KnownAbsentPropertyKeys.build(%w[__posthog_person_metadata__created_at plan], nil) + + expect(known_absent.person_keys).to eq(Set['plan']) + expect(known_absent.request_fields).to eq( + person_property_keys_known_absent: %w[__posthog_person_metadata__created_at plan] + ) + end + + describe 'group keys' do + let(:org_tier_not_set) do + flag('org-incomplete', { key: 'tier', operator: 'is_not_set', type: 'group', group_type_index: 0 }) + .tap { |definition| definition[:filters][:aggregation_group_type_index] = 0 } + end + + def group_client(definition) + local_client(definition, group_type_mapping: { '0' => 'organization', '1' => 'project' }) + end + + it 'apply to their own group type' do + c = group_client(org_tier_not_set) + + snapshot = c.evaluate_flags('user-1', flag_keys: ['org-incomplete'], groups: { organization: 'acme' }, + group_property_keys_known_absent: { organization: ['tier'] }) + + expect(snapshot.get_flag('org-incomplete')).to be(true) + expect(WebMock).not_to have_requested(:post, flags_endpoint) + end + + it 'do not apply to another group type' do + c = group_client(org_tier_not_set) + + snapshot = c.evaluate_flags('user-1', flag_keys: ['org-incomplete'], groups: { organization: 'acme' }, + only_evaluate_locally: true, + group_property_keys_known_absent: { 'project' => ['tier'] }) + + expect(snapshot.unresolved_flags).to eq('org-incomplete' => UnresolvedFlagReason::MISSING_CONTEXT) + end + + it 'do not apply to person properties' do + c = local_client(flag('incomplete', person('tier', 'is_not_set'))) + + snapshot = c.evaluate_flags('user-1', flag_keys: ['incomplete'], only_evaluate_locally: true, + group_property_keys_known_absent: { organization: ['tier'] }) + + expect(snapshot.unresolved_flags).to eq('incomplete' => UnresolvedFlagReason::MISSING_CONTEXT) + end + + it 'override the $group_key the SDK adds to group properties' do + definition = flag('no-group-key', { key: '$group_key', operator: 'is_not_set', type: 'group' }) + definition[:filters][:aggregation_group_type_index] = 0 + c = group_client(definition) + + snapshot = c.evaluate_flags('user-1', flag_keys: ['no-group-key'], groups: { organization: 'acme' }, + only_evaluate_locally: true, + group_property_keys_known_absent: { organization: ['$group_key'] }) + + expect(snapshot.get_flag('no-group-key')).to be(true) + end + + it 'apply to a group condition in a mixed-targeting flag' do + definition = flag('mixed') + definition[:filters][:groups] = [{ + properties: [{ key: 'tier', operator: 'is_not_set', type: 'group', group_type_index: 1 }], + rollout_percentage: 100, aggregation_group_type_index: 1 + }] + c = group_client(definition) + + snapshot = c.evaluate_flags('user-1', flag_keys: ['mixed'], groups: { project: 'p1' }, + only_evaluate_locally: true, + group_property_keys_known_absent: { project: ['tier'] }) + + expect(snapshot.get_flag('mixed')).to be(true) + end + end + + describe 'filters local evaluation cannot use' do + [ + ['not_icontains_multi', ['pro']], + ['not_between', [1, 2]], + ['future_operator', 'pro'], + %w[gt not-a-number], + ['not_regex', '(?=pro)'] + ].each do |operator, value| + it "stays unsupported for #{operator} #{value.inspect} on a listed key" do + property = { key: 'plan', operator: operator, value: value } + expect do + FeatureFlagsPoller.match_property(property, {}, known_absent_keys: Set['plan']) + end.to raise_error(InconclusiveMatchError) { |e| + expect(e.reason).to eq(UnresolvedFlagReason::UNSUPPORTED_DEFINITION) + } + end + end + + it 'fall back to /flags with the listed keys' do + c = local_client(flag('multi', person('plan', 'not_icontains_multi', ['pro']))) + + snapshot = c.evaluate_flags('user-1', flag_keys: ['multi'], person_property_keys_known_absent: ['plan']) + + expect(snapshot.get_flag('remote-flag')).to be(true) + expect(flags_request_body['person_property_keys_known_absent']).to eq(['plan']) + end + end + + describe 'dynamic cohorts' do + let(:cohorts) do + { + '7' => { type: 'AND', values: [{ type: 'AND', values: [ + { key: 'plan', operator: 'is_set', type: 'person', negation: true } + ] }] } + } + end + + it 'apply negation after the known-absent result' do + c = local_client(flag('no-plan-cohort', { key: 'id', value: 7, type: 'cohort' }), cohorts: cohorts) + + snapshot = c.evaluate_flags('user-1', flag_keys: ['no-plan-cohort'], only_evaluate_locally: true, + person_property_keys_known_absent: ['plan']) + + expect(snapshot.get_flag('no-plan-cohort')).to be(true) + end + end + + it 'applies to flag dependencies' do + dependency = { key: 'incomplete', type: 'flag', value: true, operator: 'flag_evaluates_to', + dependency_chain: ['incomplete'] } + c = local_client(flag('incomplete', person('plan', 'is_not_set')), flag('dependent', dependency)) + + snapshot = c.evaluate_flags('user-1', flag_keys: ['dependent'], only_evaluate_locally: true, + person_property_keys_known_absent: ['plan']) + + expect(snapshot.get_flag('dependent')).to be(true) + end + + describe 'the /flags request body' do + let(:inconclusive_flag) { flag('needs-region', person('region', 'exact', 'eu')) } + + it 'includes the listed person and group keys on fallback' do + c = local_client(inconclusive_flag) + + c.evaluate_flags('user-1', groups: { organization: 'acme' }, + person_property_keys_known_absent: ['plan'], + group_property_keys_known_absent: { organization: ['tier'] }) + + body = flags_request_body + expect(body['person_property_keys_known_absent']).to eq(['plan']) + expect(body['group_property_keys_known_absent']).to eq('organization' => ['tier']) + end + + it 'omits the fields when nothing was provided' do + c = local_client(inconclusive_flag) + + c.evaluate_flags('user-1') + + body = flags_request_body + expect(body).not_to have_key('person_property_keys_known_absent') + expect(body).not_to have_key('group_property_keys_known_absent') + end + + it 'omits empty fields' do + c = local_client(inconclusive_flag) + + c.evaluate_flags('user-1', person_property_keys_known_absent: [], + group_property_keys_known_absent: { organization: [] }) + + body = flags_request_body + expect(body).not_to have_key('person_property_keys_known_absent') + expect(body).not_to have_key('group_property_keys_known_absent') + end + + it 'includes the listed keys for the legacy single-flag getter' do + c = local_client(inconclusive_flag) + allow(Kernel).to receive(:warn) + + c.get_feature_flag_result('needs-region', 'user-1', person_property_keys_known_absent: ['plan']) + + expect(flags_request_body['person_property_keys_known_absent']).to eq(['plan']) + end + + it 'includes the listed keys for all flags and payloads' do + c = local_client(inconclusive_flag) + + c.get_all_flags_and_payloads('user-1', group_property_keys_known_absent: { organization: ['tier'] }) + + expect(flags_request_body['group_property_keys_known_absent']).to eq('organization' => ['tier']) + end + + it 'includes the listed keys for send_feature_flags on capture' do + c = local_client(inconclusive_flag) + allow(Kernel).to receive(:warn) + + c.capture(distinct_id: 'user-1', event: 'signed_up', + send_feature_flags: { person_property_keys_known_absent: ['plan'] }) + + expect(flags_request_body['person_property_keys_known_absent']).to eq(['plan']) + end + + it 'includes the listed keys for a SendFeatureFlagsOptions object on capture' do + c = local_client(inconclusive_flag) + allow(Kernel).to receive(:warn) + options = SendFeatureFlagsOptions.new(group_property_keys_known_absent: { organization: ['tier'] }) + + c.capture(distinct_id: 'user-1', event: 'signed_up', send_feature_flags: options) + + expect(flags_request_body['group_property_keys_known_absent']).to eq('organization' => ['tier']) + end + end + + describe 'limits' do + let(:too_many) { Array.new(KnownAbsentPropertyKeys::MAX_KEYS + 1, 'plan') } + + it 'accepts 1000 keys' do + c = local_client(flag('needs-region', person('region', 'exact', 'eu'))) + + c.evaluate_flags('user-1', person_property_keys_known_absent: Array.new(1000) { |i| "key-#{i}" }) + + expect(flags_request_body['person_property_keys_known_absent'].length).to eq(1000) + end + + it 'rejects more than 1000 person keys, counting duplicates, without a request' do + c = local_client(flag('needs-region', person('region', 'exact', 'eu'))) + + expect do + c.evaluate_flags('user-1', person_property_keys_known_absent: too_many) + end.to raise_error(ArgumentError, /person_property_keys_known_absent allows at most 1000 keys/) + expect(WebMock).not_to have_requested(:post, flags_endpoint) + end + + it 'rejects more than 1000 keys for one group type' do + c = local_client(flag('needs-region', person('region', 'exact', 'eu'))) + + expect do + c.get_all_flags('user-1', group_property_keys_known_absent: { organization: too_many }) + end.to raise_error(ArgumentError, /group_property_keys_known_absent\[organization\] allows at most 1000/) + expect(WebMock).not_to have_requested(:post, flags_endpoint) + end + + it 'counts group keys per group type' do + known_absent = KnownAbsentPropertyKeys.build( + nil, { organization: Array.new(1000, 'tier'), project: Array.new(1000, 'tier') } + ) + + expect(known_absent.group_keys(:project)).to eq(Set['tier']) + end + + it 'rejects inputs of the wrong type' do + expect { KnownAbsentPropertyKeys.build('plan', nil) }.to raise_error(ArgumentError) + expect { KnownAbsentPropertyKeys.build(nil, ['tier']) }.to raise_error(ArgumentError) + expect { KnownAbsentPropertyKeys.build([1], nil) }.to raise_error(ArgumentError) + end + end + end +end diff --git a/spec/posthog/send_feature_flags_options_spec.rb b/spec/posthog/send_feature_flags_options_spec.rb index 283c3a04..27f08ace 100644 --- a/spec/posthog/send_feature_flags_options_spec.rb +++ b/spec/posthog/send_feature_flags_options_spec.rb @@ -83,6 +83,20 @@ expect(options.group_properties).to eq({}) end + it 'reads known-absent property keys and round-trips them through to_h' do + hash = { + 'person_property_keys_known_absent' => ['plan'], + group_property_keys_known_absent: { company: ['tier'] } + } + options = PostHog::SendFeatureFlagsOptions.from_hash(hash) + expect(options.person_property_keys_known_absent).to eq(['plan']) + expect(options.group_property_keys_known_absent).to eq({ company: ['tier'] }) + expect(options.to_h).to include( + person_property_keys_known_absent: ['plan'], + group_property_keys_known_absent: { company: ['tier'] } + ) + end + it 'returns nil for non-hash input' do expect(PostHog::SendFeatureFlagsOptions.from_hash('not a hash')).to be_nil expect(PostHog::SendFeatureFlagsOptions.from_hash(nil)).to be_nil From 000e694ea898ae6bd5317555238af3c852d3d6af Mon Sep 17 00:00:00 2001 From: Manoel Aranda Neto Date: Thu, 19 Nov 2026 10:58:20 +0100 Subject: [PATCH 2/6] fix(flags): merge known-absent keys for String and Symbol group names --- lib/posthog/known_absent_property_keys.rb | 7 ++++++- spec/posthog/feature_flags_known_absent_spec.rb | 17 ++++++++++++++++- 2 files changed, 22 insertions(+), 2 deletions(-) diff --git a/lib/posthog/known_absent_property_keys.rb b/lib/posthog/known_absent_property_keys.rb index fc718035..6554599a 100644 --- a/lib/posthog/known_absent_property_keys.rb +++ b/lib/posthog/known_absent_property_keys.rb @@ -41,7 +41,12 @@ def self.build(person_property_keys_known_absent, group_property_keys_known_abse end group_property_keys_known_absent.each do |group_type, keys| - groups[group_type.to_s] = validate_keys(keys, "#{GROUP_FIELD}[#{group_type}]") + field = "#{GROUP_FIELD}[#{group_type}]" + # A String and a Symbol can name the same group type, so their keys are merged before the limit check. + merged = (groups[group_type.to_s] || []) + validate_keys(keys, field) + raise ArgumentError, "#{field} allows at most #{MAX_KEYS} keys, got #{merged.size}" if merged.size > MAX_KEYS + + groups[group_type.to_s] = merged end end diff --git a/spec/posthog/feature_flags_known_absent_spec.rb b/spec/posthog/feature_flags_known_absent_spec.rb index 00eaec20..e3eedb78 100644 --- a/spec/posthog/feature_flags_known_absent_spec.rb +++ b/spec/posthog/feature_flags_known_absent_spec.rb @@ -218,10 +218,14 @@ def group_client(definition) it 'fall back to /flags with the listed keys' do c = local_client(flag('multi', person('plan', 'not_icontains_multi', ['pro']))) + stub_request(:post, flags_endpoint).to_return( + status: 200, + body: { flags: { 'multi' => { key: 'multi', enabled: true, variant: nil, metadata: { id: 1 } } } }.to_json + ) snapshot = c.evaluate_flags('user-1', flag_keys: ['multi'], person_property_keys_known_absent: ['plan']) - expect(snapshot.get_flag('remote-flag')).to be(true) + expect(snapshot.get_flag('multi')).to be(true) expect(flags_request_body['person_property_keys_known_absent']).to eq(['plan']) end end @@ -367,6 +371,17 @@ def group_client(definition) expect(known_absent.group_keys(:project)).to eq(Set['tier']) end + it 'merges String and Symbol names for the same group type before the limit check' do + known_absent = KnownAbsentPropertyKeys.build(nil, { organization: ['tier'], 'organization' => ['region'] }) + + expect(known_absent.group_keys(:organization)).to eq(Set['tier', 'region']) + expect(known_absent.request_fields) + .to eq(group_property_keys_known_absent: { 'organization' => %w[tier region] }) + too_many = { organization: Array.new(600, 'tier'), 'organization' => Array.new(401, 'region') } + expect { KnownAbsentPropertyKeys.build(nil, too_many) } + .to raise_error(ArgumentError, /allows at most 1000 keys, got 1001/) + end + it 'rejects inputs of the wrong type' do expect { KnownAbsentPropertyKeys.build('plan', nil) }.to raise_error(ArgumentError) expect { KnownAbsentPropertyKeys.build(nil, ['tier']) }.to raise_error(ArgumentError) From e87f1a092350c9acc1e4e827efa1ef33b736f30f Mon Sep 17 00:00:00 2001 From: Manoel Aranda Neto Date: Thu, 19 Nov 2026 11:01:17 +0100 Subject: [PATCH 3/6] fix(flags): reject non-String group types in known-absent keys --- lib/posthog/known_absent_property_keys.rb | 4 ++++ spec/posthog/feature_flags_known_absent_spec.rb | 1 + 2 files changed, 5 insertions(+) diff --git a/lib/posthog/known_absent_property_keys.rb b/lib/posthog/known_absent_property_keys.rb index 6554599a..701f427a 100644 --- a/lib/posthog/known_absent_property_keys.rb +++ b/lib/posthog/known_absent_property_keys.rb @@ -41,6 +41,10 @@ def self.build(person_property_keys_known_absent, group_property_keys_known_abse end group_property_keys_known_absent.each do |group_type, keys| + unless group_type.is_a?(String) || group_type.is_a?(Symbol) + raise ArgumentError, "#{GROUP_FIELD} must use String or Symbol group types" + end + field = "#{GROUP_FIELD}[#{group_type}]" # A String and a Symbol can name the same group type, so their keys are merged before the limit check. merged = (groups[group_type.to_s] || []) + validate_keys(keys, field) diff --git a/spec/posthog/feature_flags_known_absent_spec.rb b/spec/posthog/feature_flags_known_absent_spec.rb index e3eedb78..a717424c 100644 --- a/spec/posthog/feature_flags_known_absent_spec.rb +++ b/spec/posthog/feature_flags_known_absent_spec.rb @@ -386,6 +386,7 @@ def group_client(definition) expect { KnownAbsentPropertyKeys.build('plan', nil) }.to raise_error(ArgumentError) expect { KnownAbsentPropertyKeys.build(nil, ['tier']) }.to raise_error(ArgumentError) expect { KnownAbsentPropertyKeys.build([1], nil) }.to raise_error(ArgumentError) + expect { KnownAbsentPropertyKeys.build(nil, { 1 => ['tier'] }) }.to raise_error(ArgumentError) end end end From 5e6534ee815bcedd1cb023cabc56e1ccbd9d2282 Mon Sep 17 00:00:00 2001 From: Manoel Aranda Neto Date: Thu, 19 Nov 2026 11:03:29 +0100 Subject: [PATCH 4/6] fix(flags): validate known-absent keys before the empty flag scope returns --- lib/posthog/client.rb | 5 +++-- spec/posthog/feature_flags_known_absent_spec.rb | 8 ++++++++ 2 files changed, 11 insertions(+), 2 deletions(-) diff --git a/lib/posthog/client.rb b/lib/posthog/client.rb index a7c79636..1de0bf62 100644 --- a/lib/posthog/client.rb +++ b/lib/posthog/client.rb @@ -736,14 +736,15 @@ def evaluate_flags( return FeatureFlagEvaluations.new(host: host, distinct_id: distinct_id, flags: {}, groups: groups) if @disabled + known_absent = KnownAbsentPropertyKeys.build(person_property_keys_known_absent, + group_property_keys_known_absent) + if flag_keys && flag_keys.empty? return FeatureFlagEvaluations.new( host: host, distinct_id: distinct_id, flags: {}, groups: groups, disable_geoip: disable_geoip ) end - known_absent = KnownAbsentPropertyKeys.build(person_property_keys_known_absent, - group_property_keys_known_absent) groups, person_properties, group_properties = add_local_person_and_group_properties( groups, person_properties, group_properties ) diff --git a/spec/posthog/feature_flags_known_absent_spec.rb b/spec/posthog/feature_flags_known_absent_spec.rb index a717424c..282f1449 100644 --- a/spec/posthog/feature_flags_known_absent_spec.rb +++ b/spec/posthog/feature_flags_known_absent_spec.rb @@ -354,6 +354,14 @@ def group_client(definition) expect(WebMock).not_to have_requested(:post, flags_endpoint) end + it 'rejects more than 1000 person keys for an empty flag scope' do + c = local_client(flag('needs-region', person('region', 'exact', 'eu'))) + + expect do + c.evaluate_flags('user-1', flag_keys: [], person_property_keys_known_absent: too_many) + end.to raise_error(ArgumentError, /person_property_keys_known_absent allows at most 1000 keys/) + end + it 'rejects more than 1000 keys for one group type' do c = local_client(flag('needs-region', person('region', 'exact', 'eu'))) From 4a9350f2da1d1d72873a4caf04a7f28efcb00da0 Mon Sep 17 00:00:00 2001 From: Manoel Aranda Neto Date: Fri, 20 Nov 2026 09:06:20 +0100 Subject: [PATCH 5/6] test(flags): cover unsupported operators in cohort leaves before known absence --- .../feature_flags_known_absent_spec.rb | 26 +++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/spec/posthog/feature_flags_known_absent_spec.rb b/spec/posthog/feature_flags_known_absent_spec.rb index 282f1449..8952d2e6 100644 --- a/spec/posthog/feature_flags_known_absent_spec.rb +++ b/spec/posthog/feature_flags_known_absent_spec.rb @@ -247,6 +247,32 @@ def group_client(definition) expect(snapshot.get_flag('no-plan-cohort')).to be(true) end + + [false, true].each do |negation| + it "check operator support before the known-absent table with negation #{negation}" do + range_cohorts = { + '8' => { type: 'AND', values: [{ type: 'AND', values: [ + { key: 'plan', operator: 'not_between', value: [1, 2], type: 'person', negation: negation } + ] }] } + } + c = local_client(flag('range-cohort', { key: 'id', value: 8, type: 'cohort' }), cohorts: range_cohorts) + stub_request(:post, flags_endpoint).to_return( + status: 200, + body: { flags: { 'range-cohort' => { key: 'range-cohort', enabled: true, variant: nil, + metadata: { id: 1 } } } }.to_json + ) + + local = c.evaluate_flags('user-1', flag_keys: ['range-cohort'], only_evaluate_locally: true, + person_property_keys_known_absent: ['plan']) + expect(local.get_flag('range-cohort')).to be_nil + expect(local.unresolved_flags).to eq('range-cohort' => UnresolvedFlagReason::UNSUPPORTED_DEFINITION) + + remote = c.evaluate_flags('user-1', flag_keys: ['range-cohort'], + person_property_keys_known_absent: ['plan']) + expect(remote.get_flag('range-cohort')).to be(true) + expect(flags_request_body['person_property_keys_known_absent']).to eq(['plan']) + end + end end it 'applies to flag dependencies' do From 65ba5e842a46315796cc43894146a31cbee7d41d Mon Sep 17 00:00:00 2001 From: Manoel Aranda Neto Date: Fri, 20 Nov 2026 10:48:28 +0100 Subject: [PATCH 6/6] ci: upgrade the SDK test harness to 1.34.0 --- .github/workflows/sdk-compliance.yml | 4 ++-- sdk_compliance_adapter/README.md | 10 +++++----- sdk_compliance_adapter/docker-compose.yml | 2 +- 3 files changed, 8 insertions(+), 8 deletions(-) diff --git a/.github/workflows/sdk-compliance.yml b/.github/workflows/sdk-compliance.yml index 84669d9f..ba5be781 100644 --- a/.github/workflows/sdk-compliance.yml +++ b/.github/workflows/sdk-compliance.yml @@ -22,11 +22,11 @@ jobs: dockerfile: sdk_compliance_adapter/Dockerfile - mode: sync dockerfile: sdk_compliance_adapter/Dockerfile.sync - uses: PostHog/posthog-sdk-test-harness/.github/workflows/test-sdk-action.yml@dde638562d33572b5c8ac3a2eafc98b92ffa2261 + uses: PostHog/posthog-sdk-test-harness/.github/workflows/test-sdk-action.yml@574c029da75e96d55c11a54d942a6df983a58ea2 with: adapter-dockerfile: ${{ matrix.dockerfile }} adapter-context: "." - test-harness-version: "1.32.0" + test-harness-version: "1.34.0" report-name: sdk-compliance-ruby-${{ matrix.mode }} sdk-type: server continue-on-error: true diff --git a/sdk_compliance_adapter/README.md b/sdk_compliance_adapter/README.md index db463020..5c17c122 100644 --- a/sdk_compliance_adapter/README.md +++ b/sdk_compliance_adapter/README.md @@ -28,14 +28,14 @@ effective default rather than changing GeoIP lookup behavior. ## Inventory and interpretation -CI uses published harness **1.32.0**, server wire format, sequential execution, and separate +CI uses published harness **1.34.0**, server wire format, sequential execution, and separate async/sync artifacts. Each profile selects **47** definitions: 30 V0 capture and 17 feature flags. Assertion failures remain advisory; a separate inventory check requires both complete reports. V1, dedicated AI and non-gzip codecs are unsupported and are not advertised. The adapter declares `synchronous_capture` only for sync mode. Published harness -1.32.0 uses that capability to check five distinct events delivered immediately +1.34.0 uses that capability to check five distinct events delivered immediately in five requests, one event per request, with unique UUIDs and no extra request on flush under `capture.batch_format.synchronous_capture_delivers_each_event_immediately`. @@ -55,9 +55,9 @@ already treats omitted/null as false. No public signature or effective privacy default changed, and the adapter does not supply a default option. The reusable workflow is pinned to release commit -`dde638562d33572b5c8ac3a2eafc98b92ffa2261`, whose release inputs pin specs commit +`574c029da75e96d55c11a54d942a6df983a58ea2`, whose release inputs pin specs commit `53e9bc16d14f973809f80049864866d5b6d9bdff`. The published V1 image digest is -`sha256:7eb6c62e2241ddd48a2dfb326652e7933cd2fe26e0ffcad98cd385d603b4eb82`. +`sha256:43f75861fbcf5bc6c3d35511caa2be2d55274054c6071ebeb943aca0bcd0633a`. Actual async and sync reports must each show 47/47 passing to establish compliance; a green advisory job or inventory check alone does not prove this. @@ -80,4 +80,4 @@ SDK_MODE=sync docker compose -f sdk_compliance_adapter/docker-compose.yml up --b For a native launch, unset `STUB` (it disables SDK HTTP), set `RUBYLIB=lib`, and run `ruby sdk_compliance_adapter/adapter.rb` with the desired `PORT` and -`SDK_MODE`. Point harness 1.32.0 at that listener and an available local mock port. +`SDK_MODE`. Point harness 1.34.0 at that listener and an available local mock port. diff --git a/sdk_compliance_adapter/docker-compose.yml b/sdk_compliance_adapter/docker-compose.yml index 1fabbf86..47647d40 100644 --- a/sdk_compliance_adapter/docker-compose.yml +++ b/sdk_compliance_adapter/docker-compose.yml @@ -9,7 +9,7 @@ services: - test-network test-harness: - image: ghcr.io/posthog/sdk-test-harness:1.32.0 + image: ghcr.io/posthog/sdk-test-harness:1.34.0@sha256:43f75861fbcf5bc6c3d35511caa2be2d55274054c6071ebeb943aca0bcd0633a command: ["run", "--adapter-url", "http://sdk-adapter:8080", "--mock-url", "http://test-harness:8081"] networks: - test-network