Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .changeset/flags-known-absent-property-keys.md
Original file line number Diff line number Diff line change
@@ -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`.
4 changes: 2 additions & 2 deletions .github/workflows/sdk-compliance.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
116 changes: 97 additions & 19 deletions lib/posthog/client.rb

Large diffs are not rendered by default.

109 changes: 76 additions & 33 deletions lib/posthog/feature_flags.rb

Large diffs are not rendered by default.

96 changes: 96 additions & 0 deletions lib/posthog/known_absent_property_keys.rb
Original file line number Diff line number Diff line change
@@ -0,0 +1,96 @@
# 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<String>] Listed person keys used for local matching.
attr_reader :person_keys

# Validates and normalizes the public inputs.
#
# @param person_property_keys_known_absent [Array<String, Symbol>, Set<String, Symbol>, nil]
# @param group_property_keys_known_absent [Hash{String, Symbol => Array<String, Symbol>}, 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|
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)
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

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<String>, 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
30 changes: 27 additions & 3 deletions lib/posthog/send_feature_flags_options.rb
Original file line number Diff line number Diff line change
Expand Up @@ -16,22 +16,42 @@ class SendFeatureFlagsOptions
# @return [Hash] Group properties to use for feature flag evaluation.
attr_reader :group_properties

# @return [Array<String, Symbol>, nil] Person property keys known to be absent.
attr_reader :person_property_keys_known_absent

# @return [Hash{String, Symbol => Array<String, Symbol>}, 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<String, Symbol>, nil] Person property keys known to be absent.
# @param group_property_keys_known_absent [Hash{String, Symbol => Array<String, Symbol>}, 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]
Expand All @@ -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
Expand Down
16 changes: 9 additions & 7 deletions public_api_snapshot.txt
Original file line number Diff line number Diff line change
Expand Up @@ -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: ...)
Expand Down Expand Up @@ -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
Expand Down
10 changes: 5 additions & 5 deletions sdk_compliance_adapter/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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`.
Expand All @@ -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.

Expand All @@ -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.
2 changes: 1 addition & 1 deletion sdk_compliance_adapter/docker-compose.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Loading