Repository navigation
feat(flags): support known-absent property keys in local evaluation - #369
marandaneto wants to merge 6 commits into
Conversation
posthog-ruby-sync Compliance ReportDate: 2026-11-20T09:50:41.276080+00:00 ✅ All Tests Passed!47/47 tests passed Capture Tests✅ 30/30 tests passed View Details
Feature_Flags Tests✅ 17/17 tests passed View Details
|
posthog-ruby-async Compliance ReportDate: 2026-11-20T09:50:37.966753+00:00 ✅ All Tests Passed!47/47 tests passed Capture Tests✅ 30/30 tests passed View Details
Feature_Flags Tests✅ 17/17 tests passed View Details
|
SDK performance: posthog-ruby1 change worth reviewing: 1 observed regression. Flags require at least a 5% change in the median and all six pairs agreeing on direction. This is a noise filter, not proof of a performance change or a CI gate.
View all results
Values are medians of paired measurements. Not flagged does not mean unchanged. Unavailable means a measurement could not be provided, not zero. Estimated allocation measurements retain their instrumentation uncertainty. RSS measures the whole process, not just SDK allocations; observed peaks are sampled checkpoints. Paired ranges in the diagnostics describe variability, not confidence intervals. Each shard uses its own runner; compare Before PR against With PR within a row, not across shards. Compared 102 metric rows; 102 rows shown in all results. Omitted or shortened data remain in |
PR overviewNo security issues were found in this pull request. Reviews
|
💡 Motivation and Context
Local flag evaluation can't tell "the caller didn't pass
plan" from "this person has noplan". A key left out ofperson_propertiesis inconclusive. So a condition likeplan is_not_setcan't resolve locally, and the SDK falls back to/flags. Callers who know a person has noplanhad no way to say so. Local results and the/flagsfallback could then disagree.This adds an optional way to list property keys that are known to be absent. It follows the cross-SDK spec in PostHog/sdk-specs#233 and the backend support in PostHog/posthog#138239.
Issue: PostHog/posthog#88947
New input
Every flag evaluation method now accepts two optional keyword arguments:
person_property_keys_known_absent:takes an Array of String or Symbol keys.group_property_keys_known_absent:takes a Hash from group type name to an Array of keys.These methods accept them:
evaluate_flags,get_feature_flag,get_feature_flag_result,is_feature_enabled,get_feature_flag_payload,get_all_flagsandget_all_flags_and_payloads.SendFeatureFlagsOptionsalso accepts them, and so does the hash form ofcapture(send_feature_flags:). Both default tonil, so existing calls behave the same.Local evaluation behavior
is_not_set,is_not,not_icontains,not_starts_with,not_ends_withandnot_regexmatch. Every other operator does not match. That includesis_set,exact, thecontains/starts_with/ends_with/regexchecks, number comparisons, allsemver_*operators includingsemver_neq, and the date operators.distinct_idin person properties and$group_keyin group properties./flagsas before, even for a listed key.dynamic cohorts check operator support before the known-absent tablecovers a cohort leafplan not_between [1, 2]with and without negation.__posthog_person_metadata__are ignored for local matching. They are still sent to/flagsas given./flagsrequest bodyWhen a call falls back to
/flags, or skips local evaluation, the request includesperson_property_keys_known_absent: [...]andgroup_property_keys_known_absent: { group_type => [...] }. A field is left out when the caller did not provide it or when it is empty.Limits
Each list holds at most 1000 keys, counting duplicates. For groups the limit applies per group type. A longer list raises
ArgumentErrorbefore any evaluation or request. The list is never truncated. Lists that are not an Array or Set, keys that are not a String or Symbol, and group types that are not a String or Symbol also raiseArgumentError.Not included
$feature_enrollment/<flag>keys. Only posthog-python evaluates enrollment locally today. Tracked in Support local feature enrollment evaluation across server SDKs posthog#138580.icontains_multi,not_icontains_multi,betweenandnot_betweenoperators. Ruby doesn't support them yet, so they still fall back to/flagseven for a listed key. Tracked in Support icontains_multi and between operators in SDK local flag evaluation posthog#138581.feature_flags_local_evaluation_v1orfeature_flags_known_absent_v1.Follow-up
This gap already exists on
mainand this PR does not change it. When a condition depends on another flag, the SDK evaluates that flag with the calling condition's properties and bucketing ID. It does not use the dependency's own person or group context, and it does not passgroupsorgroup_properties. So a dependency can give a different result than evaluating that flag directly. This happens when the dependency targets a different person or group context than the condition that references it, for example inside a flag that mixes person and group conditions. Known-absent keys follow the same properties, so they inherit this gap. Autoreview flagged it on every round. It should be fixed in a separate PR.Links
💚 How did you test it?
New tests in
spec/posthog/feature_flags_known_absent_spec.rbandspec/posthog/send_feature_flags_options_spec.rbcover:distinct_idand$group_key/flagsnot_betweenleaf in a dynamic cohort, with and without negation, staying unresolved withunsupported_definitionand falling back to/flagsfor a listed key. The new test passed without production changes, and it fails if the support check is removed./flagsbody including the fields on fallback forevaluate_flags, the older getters, all flags and payloads, andcapture(send_feature_flags:), and leaving them out when they are missing or emptyflag_keysscope, plus wrong input typesCommands run on the final commit:
bundle exec rspec: 2643 examples, 0 failures, 49 pendingbundle exec rubocop: no offensesbundle exec rake public_api:check: passedThe otel gemfile suite was not run locally. No manual testing against a live PostHog project was done.
📝 Checklist
If releasing new changes
pnpm changesetto generate a changeset file🤖 Agent context
Autonomy: Human-driven (agent-assisted)
Implemented and reviewed with the pi coding agent, using Claude. Autoreview with GPT ran four rounds against
origin/main. Accepted findings were fixed in separate signed commits. Those fixes merge String and Symbol group names, reject non-String group types, and check the key limit beforeevaluate_flagsreturns early for an emptyflag_keys. Every round also flagged the dependency context gap under "Follow-up". It already exists onmain, so it was left out of this PR. The last round reviewed the final commit and found only that gap.