:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
use crate::api::errors::FlagError;
use crate::api::types::{FlagDetails, FlagValue, FlagsResponse, FromFeatureAndMatch};
use crate::cohorts::cohort_cache_manager::CohortCacheManager;
use crate::cohorts::cohort_models::{Cohort, CohortId, CohortMembership, MembershipStampPolicy};
use crate::cohorts::cohort_operations::{
apply_cohort_membership_logic, evaluate_dynamic_cohorts, record_stamp_policy_divergence,
};
use crate::cohorts::membership::{CohortMembershipProvider, NoOpCohortMembershipProvider};
use crate::database::{pool_names, PostgresRouter};
use crate::flags::config_v2::{Config, NonV1Config};
use crate::flags::evaluate_v2::{
Evaluation, EvaluationContext, EvaluationDetail, Evaluator, PersonProperties,
};
use crate::flags::flag_group_type_mapping::{
GroupTypeCacheManager, GroupTypeIndex, GroupTypeMapping,
};
use crate::flags::flag_match_reason::FeatureFlagMatchReason;
use crate::flags::flag_matching_utils::{
calculate_hash, db_operations, failed_flag_dependency,
fetch_and_locally_cache_all_relevant_properties, get_feature_flag_hash_key_overrides,
match_flag_value_to_flag_filter, populate_missing_initial_properties, populate_os_aliases,
set_feature_flag_hash_key_overrides, should_write_hash_key_override, track_unretried_db_error,
};
use crate::flags::flag_models::{
default_has_experiment, FeatureFlag, FeatureFlagId, FeatureFlagList, FlagFilters,
FlagPropertyGroup,
};
use crate::flags::flag_operations::flags_require_db_preparation;
use crate::handler::canonical_log::{install_rayon_canonical_log, take_rayon_canonical_log};
use crate::handler::with_canonical_log;
use crate::metrics::consts::{
DB_PERSON_AND_GROUP_PROPERTIES_READS_COUNTER, FLAG_BATCH_EVALUATION_COUNTER,
FLAG_BATCH_EVALUATION_TIME, FLAG_BATCH_SIZE, FLAG_COHORT_SOURCE_COUNTER,
FLAG_CONDITION_SKIPPED_COUNTER, FLAG_DB_PROPERTIES_FETCH_TIME,
FLAG_EVALUATE_ALL_CONDITIONS_TIME, FLAG_EVALUATION_ERROR_COUNTER, FLAG_EVALUATION_TIME,
FLAG_EXPERIENCE_CONTINUITY_OPTIMIZED, FLAG_EXPERIENCE_CONTINUITY_REQUESTS_COUNTER,
FLAG_GET_MATCH_TIME, FLAG_GROUP_CACHE_FETCH_TIME, FLAG_GROUP_DB_FETCH_TIME,
FLAG_HASH_KEY_PROCESSING_TIME, FLAG_HASH_KEY_WRITES_COUNTER,
FLAG_REALTIME_COHORT_QUERY_ERROR_COUNTER, FLAG_REALTIME_COHORT_QUERY_TIME,
PROPERTY_CACHE_HITS_COUNTER, PROPERTY_CACHE_MISSES_COUNTER,
};
use crate::properties::property_matching::{match_property, PropertyMatchingContext};
use crate::properties::property_models::{PropertyFilter, PropertyType};
use crate::rayon_dispatcher::RayonDispatcher;
use crate::utils::deadline::before_deadline;
use crate::utils::graph_utils::PrecomputedDependencyGraph;
use anyhow::Result;
use chrono::{DateTime, Utc};
use chrono_tz::Tz;
use common_metrics::{histogram, inc, timing_guard, timing_guard_high_precision};
use common_types::collections::HashMapExt;
use common_types::{PersonId, TeamId};
use rayon::prelude::*;
use serde_json::Value;
use std::collections::{HashMap, HashSet};
use std::future::Future;
use std::sync::Arc;
use tokio::time::Instant;
use tracing::{debug, error, instrument, warn};
use uuid::Uuid;
const DEFAULT_PARALLEL_EVAL_THRESHOLD: usize = 100;
/// Parameters for feature flag evaluation with various override options
#[derive(Debug, Default)]
pub struct FlagEvaluationOverrides {
pub person_property_overrides: Option<HashMap<String, Value>>,
pub group_property_overrides: Option<HashMap<String, HashMap<String, Value>>>,
pub hash_key_overrides: Option<HashMap<String, String>>,
pub hash_key_override_error: bool,
/// The request's anon_distinct_id, used as a fallback for EEC flags when no DB override exists
pub request_hash_key_override: Option<String>,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum EvaluationType {
Sequential,
Parallel,
}
impl EvaluationType {
pub const fn as_str(self) -> &'static str {
match self {
EvaluationType::Sequential => "sequential",
EvaluationType::Parallel => "parallel",
}
}
/// Promote evaluation type across dependency levels:
/// None → Sequential, None → Parallel, Sequential → Parallel.
/// Parallel is sticky — once set, it never demotes back to Sequential.
pub fn promote(current: Option<Self>, level_type: Self) -> Option<Self> {
match (current, level_type) {
(_, Self::Parallel) => Some(Self::Parallel),
(None, Self::Sequential) => Some(Self::Sequential),
(current, Self::Sequential) => current,
}
}
}
impl std::fmt::Display for EvaluationType {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
f.write_str(self.as_str())
}
}
#[derive(Debug, PartialEq, Eq, Clone)]
pub struct FeatureFlagMatch {
pub matches: bool,
pub variant: Option<String>,
pub reason: FeatureFlagMatchReason,
pub condition_index: Option<usize>,
pub payload: Option<Value>,
/// Set only by `get_match_v2`; the v4 record is built from it.
pub evaluation_v2: Option<EvaluationDetail>,
}
impl FeatureFlagMatch {
pub fn get_flag_value(&self) -> FlagValue {
match (self.matches, &self.variant) {
(true, Some(variant)) => FlagValue::String(variant.clone()),
(true, None) => FlagValue::Boolean(true),
(false, _) => FlagValue::Boolean(false),
}
}
/// Creates a match result for flags with missing dependencies.
/// These flags evaluate to `false` (fail closed) with the `MissingDependency` reason.
pub fn missing_dependency() -> Self {
Self {
matches: false,
variant: None,
reason: FeatureFlagMatchReason::MissingDependency,
condition_index: None,
payload: None,
evaluation_v2: None,
}
}
}
/// Tracks person property state through the evaluation lifecycle.
///
/// Combines fetch status with property data so that impossible states (e.g. "fetched"
/// but no properties) are unrepresentable. When request overrides cover all needed keys,
/// DB prep is skipped and this stays `Skipped`. When DB prep runs, properties are stored
/// directly in the `Fetched` variant.
#[derive(Clone, Debug, Default)]
pub(crate) enum PersonPropertyState {
/// DB prep has not yet run (initial state)
#[default]
Pending,
/// DB prep was skipped because request overrides covered all needed property keys
Skipped,
/// DB prep ran and populated person properties
Fetched(HashMap<String, Value>),
}
/// Outcome of the group type mapping lookup for a request.
///
/// The mapping resolves a group type index to the name the request keys its `groups` by, so
/// without it there is no way to tell "the caller sent no group of this type" from "the lookup
/// failed". Keeping the failure in the same value as the mapping stops those two from being
/// answered independently — see `FeatureFlagMatcher::filter_needs_partial_props`.
#[derive(Clone, Debug, Default)]
enum GroupTypeMappingState {
/// The lookup has not run for this request (initial state)
#[default]
Uninitialized,
/// The lookup ran and returned a mapping, which may be empty for a team with no group types
Loaded(GroupTypeMapping),
/// The lookup ran and failed
Failed(Arc<FlagError>),
}
impl GroupTypeMappingState {
fn mapping(&self) -> Option<&GroupTypeMapping> {
match self {
Self::Loaded(mapping) => Some(mapping),
_ => None,
}
}
}
/// This struct maintains evaluation state by caching database-sourced data during feature flag evaluation.
/// It stores person IDs, properties, group properties, and cohort matches that are fetched from the database,
/// allowing them to be reused across multiple flag evaluations within the same request without additional DB lookups.
///
/// The cache is scoped to a single evaluation session and is cleared between different requests.
#[derive(Clone, Default, Debug)]
pub struct FlagEvaluationState {
/// The person ID associated with the distinct_id being evaluated
person_id: Option<PersonId>,
/// The person UUID, needed for realtime cohort membership lookups
person_uuid: Option<Uuid>,
/// Person property fetch state: pending, skipped, or fetched (with property data)
person_property_state: PersonPropertyState,
/// Properties for each group type whose properties DB prep ran for this evaluation.
///
/// The key set carries the group-level analogue of `PersonPropertyState`: a missing index
/// means the fetch never ran, so nothing about that group type's properties is known. A
/// present index means the fetch ran and its map is authoritative, so an empty map means
/// the group genuinely has no properties (no `posthog_group` row).
group_properties: HashMap<GroupTypeIndex, HashMap<String, Value>>,
/// Cohorts for the current request, shared via `Arc` either from the
/// preloaded hypercache slice or wrapped from a `CohortCacheManager`
/// fetch.
cohorts: Option<Arc<[Cohort]>>,
/// Cache of cohort membership results (both static and realtime) to avoid repeated lookups.
/// Static results come from `posthog_cohortpeople`, realtime results from `cohort_membership`.
/// The two sources produce disjoint key sets partitioned by `CohortType`.
cohort_matches: Option<HashMap<CohortId, bool>>,
/// Cache of flag evaluation results to avoid repeated DB lookups
flag_evaluation_results: HashMap<FeatureFlagId, FlagValue>,
failed_flag_ids: HashSet<FeatureFlagId>,
}
impl FlagEvaluationState {
pub fn get_person_id(&self) -> Option<PersonId> {
self.person_id
}
pub fn get_person_properties(&self) -> Option<&HashMap<String, Value>> {
match &self.person_property_state {
PersonPropertyState::Fetched(props) => Some(props),
_ => None,
}
}
/// True when person-property DB prep never ran (neither fetched nor deliberately
/// skipped in favor of overrides). Distinct from `Skipped`, where overrides are
/// known to cover every property the batch needs — see `PersonPropertyState`.
pub(crate) fn person_properties_pending(&self) -> bool {
matches!(self.person_property_state, PersonPropertyState::Pending)
}
pub fn get_group_properties(&self) -> &HashMap<GroupTypeIndex, HashMap<String, Value>> {
&self.group_properties
}
pub fn get_cohort_matches(&self) -> Option<&HashMap<CohortId, bool>> {
self.cohort_matches.as_ref()
}
pub fn get_person_uuid(&self) -> Option<Uuid> {
self.person_uuid
}
pub fn set_person_id(&mut self, id: PersonId) {
self.person_id = Some(id);
}
pub fn set_person_uuid(&mut self, uuid: Uuid) {
self.person_uuid = Some(uuid);
}
pub fn set_person_properties(&mut self, properties: HashMap<String, Value>) {
self.person_property_state = PersonPropertyState::Fetched(properties);
}
pub fn skip_person_properties(&mut self) {
self.person_property_state = PersonPropertyState::Skipped;
}
pub fn set_cohorts(&mut self, cohorts: Arc<[Cohort]>) {
self.cohorts = Some(cohorts);
}
pub fn set_group_properties(
&mut self,
group_type_index: GroupTypeIndex,
properties: HashMap<String, Value>,
) {
self.group_properties.insert(group_type_index, properties);
}
/// Record that group-property DB prep ran for this group type, without disturbing
/// properties already stored for it. Must be called for every requested index once the
/// fetch succeeds, including indexes the query returned no row for — an empty map there
/// is an authoritative "this group has no properties", not a missing fetch.
pub fn mark_group_properties_fetched(&mut self, group_type_index: GroupTypeIndex) {
self.group_properties.entry(group_type_index).or_default();
}
/// True when group-property DB prep never ran for this group type, so an absent
/// key in the resolved property map carries no information — see `group_properties`.
pub(crate) fn group_properties_pending(&self, group_type_index: GroupTypeIndex) -> bool {
!self.group_properties.contains_key(&group_type_index)
}
pub fn set_cohort_matches(&mut self, matches: HashMap<CohortId, bool>) {
self.cohort_matches = Some(matches);
}
/// Merge additional cohort membership results into the existing map.
/// Used to add realtime cohort results after static results are already set.
pub fn merge_cohort_matches(&mut self, additional: HashMap<CohortId, bool>) {
match &mut self.cohort_matches {
Some(existing) => existing.extend(additional),
None => self.cohort_matches = Some(additional),
}
}
pub fn add_flag_evaluation_result(&mut self, flag_id: FeatureFlagId, flag_value: FlagValue) {
self.flag_evaluation_results.insert(flag_id, flag_value);
}
fn failed_dependency(&self, filter: &PropertyFilter) -> Option<FeatureFlagId> {
failed_flag_dependency(filter, &self.flag_evaluation_results, &self.failed_flag_ids)
}
/// Returns true when no single value of some failed flag satisfies all of the filters on that
/// flag, for example `true` together with `false`, or two different variants.
/// `is_condition_match` passes each filter on a failed flag on its own. This check finds the
/// conflict that those separate passes miss.
fn failed_dependency_filters_conflict(&self, filters: &[PropertyFilter]) -> bool {
let mut filters_by_flag: HashMap<FeatureFlagId, Vec<&PropertyFilter>> = HashMap::new();
for filter in filters {
if let Some(flag_id) = self.failed_dependency(filter) {
filters_by_flag.entry(flag_id).or_default().push(filter);
}
}
filters_by_flag
.into_iter()
.any(|(flag_id, filters_on_flag)| {
if filters_on_flag.len() < 2 {
return false;
}
let variants = filters_on_flag
.iter()
.filter_map(|filter| match &filter.value {
Some(Value::String(variant)) => Some(FlagValue::String(variant.clone())),
_ => None,
});
// A variant that no filter names passes the same filters as `true`.
let can_match = [FlagValue::Boolean(false), FlagValue::Boolean(true)]
.into_iter()
.chain(variants)
.any(|value| {
let results = HashMap::from([(flag_id, value)]);
filters_on_flag
.iter()
.all(|filter| match_flag_value_to_flag_filter(filter, &results))
});
!can_match
})
}
}
#[derive(Debug, PartialEq)]
enum ConditionAnswer {
Match(Option<String>),
NoMatch,
}
impl ConditionAnswer {
fn is_match(&self) -> bool {
matches!(self, ConditionAnswer::Match(_))
}
}
struct AnswerIfDependencyMatched {
failed_dependency: FeatureFlagId,
answer: ConditionAnswer,
}
static EMPTY_PROPERTY_MAP: std::sync::LazyLock<HashMap<String, Value>> =
std::sync::LazyLock::new(HashMap::new);
/// Bundles references to the property maps and aggregation mode needed during
/// condition matching. A condition may reference both person and group properties
/// (mixed targeting), so this struct carries both sources and routes each filter
/// to the correct one.
pub(crate) struct PropertyContext<'a> {
pub person_properties: Option<&'a HashMap<String, Value>>,
pub group_properties: &'a HashMap<GroupTypeIndex, HashMap<String, Value>>,
pub aggregation: Option<GroupTypeIndex>,
pub request_has_group_context: bool,
}
impl PropertyContext<'_> {
/// Resolves the correct property map for a filter based on its type. Person filters
/// use person properties, group filters use the group properties for the filter's
/// `group_type_index`. Falls back to aggregation mode for legacy filters without
/// an explicit type distinction.
pub fn resolve_for_filter(&self, filter: &PropertyFilter) -> &HashMap<String, Value> {
match filter.prop_type {
// PersonMetadata fields (e.g. created_at) are injected into the same map as
// regular person properties; see the `result.person` block in
// `apply_person_cohort_to_state` (flag_matching_utils.rs).
PropertyType::Person | PropertyType::PersonMetadata => {
self.person_properties.unwrap_or(&*EMPTY_PROPERTY_MAP)
}
PropertyType::Group => filter
.group_filter_index(self.aggregation)
.and_then(|idx| self.group_properties.get(&idx))
.unwrap_or(&*EMPTY_PROPERTY_MAP),
PropertyType::Cohort | PropertyType::Flag => match self.aggregation {
Some(gti) => self
.group_properties
.get(>i)
.unwrap_or(&*EMPTY_PROPERTY_MAP),
None => self.person_properties.unwrap_or(&*EMPTY_PROPERTY_MAP),
},
}
}
}
/// Evaluates feature flags for a specific user/group context.
///
/// This struct maintains the state and logic needed to evaluate feature flags, including:
/// - User identification (distinct_id, team_id)
/// - Database connections for fetching data
/// - Caches for properties, cohorts, and group mappings to optimize performance
/// - Evaluation state that persists across multiple flag evaluations in a request
///
/// The matcher is typically created once per request and can evaluate multiple flags
/// efficiently by reusing cached data and DB connections.
#[derive(Clone)]
pub struct FeatureFlagMatcher {
/// Unique identifier for the user/entity being evaluated
pub distinct_id: String,
/// Optional device identifier for device-level bucketing
pub device_id: Option<String>,
/// Team ID for scoping flag evaluations
pub team_id: TeamId,
/// Router for database connections across persons/non-persons pools
pub router: PostgresRouter,
/// Cache manager for cohort definitions and memberships
pub cohort_cache: Arc<CohortCacheManager>,
/// Shared in-process cache for group type mappings
group_type_cache: Arc<GroupTypeCacheManager>,
/// Outcome of the group type mapping lookup for the current team, fetched once per
/// request via `group_type_cache`.
group_type_mapping: GroupTypeMappingState,
/// State maintained during flag evaluation, including cached DB lookups
pub(crate) flag_evaluation_state: FlagEvaluationState,
/// Group key mappings for group-based flag evaluation
/// Maps group type name to the group key (identifier customer supplies for the group)
/// ex. "project" → "123"
/// "organization" → "456"
/// "instance" → "789"
/// "customer" → "101"
/// "team" → "112"
groups: HashMap<String, Value>,
/// Flag count threshold for switching from sequential to parallel evaluation.
/// Configured via PARALLEL_EVAL_THRESHOLD env var in production.
parallel_eval_threshold: usize,
/// Dispatcher for bounded-concurrency Rayon batch evaluation.
/// `None` in tests that don't exercise the parallel path.
rayon_dispatcher: Option<RayonDispatcher>,
/// When true, skip all writes to PostgreSQL and Redis.
skip_writes: bool,
/// Keys of flags whose variant neither the caller nor any evaluated flag reads. A failed
/// dependency fails one of these flags only when it could change whether the flag matches.
/// Every other flag keeps the variant comparison.
enabled_only_flag_keys: HashSet<String>,
/// Flag IDs that should be skipped during evaluation.
/// Populated once per request from `FeatureFlagList::filtered_out_flag_ids`.
pub(crate) filtered_out_flag_ids: HashSet<i32>,
/// Provider for realtime/behavioral cohort membership lookups.
/// Queries the behavioral cohorts database for cohorts with CohortType::Realtime or Behavioral.
cohort_membership_provider: Arc<dyn CohortMembershipProvider>,
/// Whether to enable realtime cohort evaluation.
/// When false, realtime cohorts are treated as non-members.
enable_realtime_cohort_evaluation: bool,
use_explicit_exact_matching: bool,
membership_stamp_policy: MembershipStampPolicy,
/// Cohort definitions preloaded from the flags hypercache.
/// When present, scoped to only the cohorts referenced by flags (including transitive deps),
/// so the matcher skips the CohortCacheManager PG query entirely.
/// `None` means no preloaded data (PG fallback or old cache) — use CohortCacheManager.
preloaded_cohorts: Option<Arc<[Cohort]>>,
/// Whether to include detailed condition analysis in flag evaluation results.
detailed_analysis: bool,
/// Whether to only use person properties from request payload, ignoring database properties.
only_use_override_person_properties: bool,
/// Team timezone used to interpret naive datetime filter values (IS_DATE_* and
/// relative dates), so flag evaluation matches HogQL/ClickHouse cohort behavior.
/// Parsed once per request and reused across every property comparison.
timezone: Tz,
/// Request evaluation time. Only v2 relative-date predicates read it; tests pin it.
now: DateTime<Utc>,
/// Every persons DB call in this evaluation fails once this instant passes. `None` leaves
/// each call bounded only by the pool acquire timeout and statement_timeout.
persons_db_deadline: Option<Instant>,
}
/// Lightweight snapshot of a flag's identity fields, saved before moving
/// flags into the Rayon pool. Used to reconstruct per-flag error results
/// if the rayon task panics.
struct FlagSnapshot {
key: String,
id: FeatureFlagId,
version: Option<i32>,
/// Keeps a v2 flag's error record labelled v2.
non_v1: Option<Arc<NonV1Config>>,
}
impl FlagSnapshot {
pub fn from_flag(flag: &FeatureFlag) -> Self {
FlagSnapshot {
key: flag.key.clone(),
id: flag.id,
version: flag.version,
non_v1: flag.filters.non_v1.clone(),
}
}
}
/// Mirrors Python's `add_local_person_and_group_properties` so flag conditions
/// matching on `distinct_id` evaluate without a DB lookup. Always injects the
/// request `distinct_id` (including `""`) unless an explicit
/// `person_property_overrides["distinct_id"]` is already present, in which case
/// the explicit override wins.
fn merge_distinct_id_into_person_properties(
distinct_id: &str,
overrides: Option<HashMap<String, Value>>,
) -> HashMap<String, Value> {
let mut overrides = overrides.unwrap_or_default();
overrides
.entry("distinct_id".to_string())
.or_insert_with(|| Value::String(distinct_id.to_string()));
overrides
}
fn ids_of_failed_flags<'a>(
details: impl Iterator<Item = &'a FlagDetails> + 'a,
) -> impl Iterator<Item = FeatureFlagId> + 'a {
details
.filter(|details| details.failed)
.map(|details| details.metadata.id)
}
fn is_usable_group_key(group_key: &Value) -> bool {
match group_key {
Value::String(s) => !s.is_empty(),
Value::Number(_) => true,
_ => false,
}
}
// This is a plain fn rather than an `async fn` so that it boxes `call` before any async state
// captures it. An `async fn` would store `call` in its own state. The `before_deadline` and
// `timeout_at` futures store it again. In debug builds those copies grow the /flags handler
// future enough to overflow a 2 MiB thread stack.
fn before_persons_db_deadline<T>(
deadline: Option<Instant>,
operation: &'static str,
call: impl Future<Output = Result<T, FlagError>>,
) -> impl Future<Output = Result<T, FlagError>> {
let call = Box::pin(call);
async move {
let result = before_deadline(deadline, call, FlagError::persons_db_deadline).await;
record_persons_db_deadline_exceeded(operation, &result);
result
}
}
fn record_persons_db_deadline_exceeded<T>(operation: &'static str, result: &Result<T, FlagError>) {
let Err(e) = result else {
return;
};
if !e.is_persons_db_deadline() {
return;
}
track_unretried_db_error(e, operation);
with_canonical_log(|log| {
log.persons_db_deadline_exceeded.get_or_insert(operation);
});
}
/// The one place a failed flag is built, so the request outcome sees every failure.
fn failed_flag_details(flag: &FeatureFlag, error: &FlagError) -> FlagDetails {
with_canonical_log(|log| log.outcome_marks.mark_flag_failed(error));
FlagDetails::create_error(flag, error, None)
}
impl FeatureFlagMatcher {
#[allow(clippy::too_many_arguments)]
pub fn new(
distinct_id: String,
device_id: Option<String>,
team_id: TeamId,
router: PostgresRouter,
cohort_cache: Arc<CohortCacheManager>,
group_type_cache: Arc<GroupTypeCacheManager>,
groups: Option<HashMap<String, Value>>,
) -> Self {
FeatureFlagMatcher {
distinct_id,
device_id,
team_id,
router,
cohort_cache,
group_type_cache,
group_type_mapping: GroupTypeMappingState::default(),
groups: groups.unwrap_or_default(),
flag_evaluation_state: FlagEvaluationState::default(),
cohort_membership_provider: Arc::new(NoOpCohortMembershipProvider),
parallel_eval_threshold: DEFAULT_PARALLEL_EVAL_THRESHOLD,
rayon_dispatcher: None,
skip_writes: false,
enabled_only_flag_keys: HashSet::new(),
filtered_out_flag_ids: HashSet::new(),
enable_realtime_cohort_evaluation: false,
use_explicit_exact_matching: false,
membership_stamp_policy: MembershipStampPolicy::default(),
preloaded_cohorts: None,
detailed_analysis: false,
only_use_override_person_properties: false,
timezone: Tz::UTC,
now: Utc::now(),
persons_db_deadline: None,
}
}
pub fn with_now(mut self, now: DateTime<Utc>) -> Self {
self.now = now;
self
}
/// Sets the team timezone used to interpret naive datetime filter values.
/// Defaults to UTC; production must thread the team's timezone through so flag
/// evaluation agrees with HogQL/ClickHouse cohort membership near day boundaries.
pub fn with_timezone(mut self, timezone: Tz) -> Self {
self.timezone = timezone;
self
}
pub fn with_parallel_eval_threshold(mut self, threshold: usize) -> Self {
self.parallel_eval_threshold = threshold;
self
}
pub fn with_rayon_dispatcher(mut self, dispatcher: RayonDispatcher) -> Self {
self.rayon_dispatcher = Some(dispatcher);
self
}
pub fn with_skip_writes(mut self, skip_writes: bool) -> Self {
self.skip_writes = skip_writes;
self
}
pub fn with_enabled_only_flag_keys(mut self, flag_keys: HashSet<String>) -> Self {
self.enabled_only_flag_keys = flag_keys;
self
}
pub fn with_cohort_membership_provider(
mut self,
provider: Arc<dyn CohortMembershipProvider>,
) -> Self {
self.cohort_membership_provider = provider;
self
}
pub fn with_realtime_cohort_evaluation(mut self, enable: bool) -> Self {
self.enable_realtime_cohort_evaluation = enable;
self
}
pub fn with_explicit_exact_matching(mut self, enable: bool) -> Self {
self.use_explicit_exact_matching = enable;
self
}
pub fn with_membership_stamp_policy(mut self, policy: MembershipStampPolicy) -> Self {
self.membership_stamp_policy = policy;
self
}
pub fn with_detailed_analysis(mut self, detailed_analysis: bool) -> Self {
self.detailed_analysis = detailed_analysis;
self
}
pub fn with_only_use_override_person_properties(mut self, only_use_override: bool) -> Self {
self.only_use_override_person_properties = only_use_override;
self
}
/// Gives all persons DB work in this evaluation one shared deadline.
pub fn with_persons_db_deadline(mut self, deadline: Option<Instant>) -> Self {
self.persons_db_deadline = deadline;
self
}
/// Evaluates all feature flags for the current matcher context.
///
/// ## Arguments
///
/// * `feature_flags` - The list of feature flags to evaluate.
/// * `person_property_overrides` - Any overrides for person properties.
/// * `group_property_overrides` - Any overrides for group properties.
/// * `hash_key_override` - Optional hash key overrides for experience continuity.
/// * `optimize_experience_continuity_lookups` - When true, skip lookups for flags that don't need them.
///
/// ## Returns
///
/// * `FlagsResponse` - The result containing flag evaluations and any errors.
#[instrument(skip_all, fields(team_id = %self.team_id, distinct_id = %self.distinct_id, flags_len = feature_flags.flags.len()))]
#[allow(clippy::too_many_arguments)]
pub async fn evaluate_all_feature_flags(
&mut self,
feature_flags: FeatureFlagList,
person_property_overrides: Option<HashMap<String, Value>>,
group_property_overrides: Option<HashMap<String, HashMap<String, Value>>>,
hash_key_override: Option<String>, // Aka $anon_distinct_id
request_id: Uuid,
flag_keys: Option<Vec<String>>,
optimize_experience_continuity_lookups: bool,
) -> Result<FlagsResponse, FlagError> {
let eval_timer = common_metrics::timing_guard(FLAG_EVALUATION_TIME, &[]);
let person_property_overrides = Some(merge_distinct_id_into_person_properties(
&self.distinct_id,
person_property_overrides,
));
let precomputed = PrecomputedDependencyGraph::build(&feature_flags, flag_keys.as_deref());
self.filtered_out_flag_ids = feature_flags.filtered_out_flag_ids;
self.preloaded_cohorts = feature_flags.cohorts;
let PrecomputedDependencyGraph {
error_count,
has_cycle_errors,
evaluation_stages,
flags_with_missing_deps,
} = precomputed;
if error_count > 0 {
with_canonical_log(|log| log.dependency_graph_errors = error_count);
}
// Compute experience continuity stats from the filtered graph.
// This considers all flags that will actually be evaluated (including dependencies).
let (experience_continuity_count, any_flag_needs_override) = {
let mut continuity_count = 0;
let mut needs_override = false;
for flag in evaluation_stages.iter().flatten() {
if !self.filtered_out_flag_ids.contains(&flag.id)
&& flag.has_experience_continuity()
{
continuity_count += 1;
if !needs_override && flag.needs_hash_key_override() {
needs_override = true;
}
}
}
(continuity_count, needs_override)
};
// Log the experience continuity count from the filtered graph
with_canonical_log(|log| log.flags_experience_continuity = experience_continuity_count);
let has_experience_continuity = experience_continuity_count > 0;
// Determine if we need to do the hash key override lookup.
// In legacy mode (optimization disabled), we always do the lookup if any flag has continuity.
// In optimized mode, we only do it if any flag actually needs it.
let do_hash_key_lookup = if optimize_experience_continuity_lookups {
any_flag_needs_override
} else {
has_experience_continuity
};
// A request is optimizable when it has experience continuity flags but none require the lookup
let request_is_optimizable = has_experience_continuity && !any_flag_needs_override;
// Track optimization metric: status="skipped" when we skip, "eligible" when we could have
if request_is_optimizable {
let status = if optimize_experience_continuity_lookups {
"skipped"
} else {
"eligible"
};
inc(
FLAG_EXPERIENCE_CONTINUITY_OPTIMIZED,
&[
("status".to_string(), status.to_string()),
("team_id".to_string(), self.team_id.to_string()),
],
1,
);
}
// Record when the optimization actually skips the lookup
if request_is_optimizable && optimize_experience_continuity_lookups {
with_canonical_log(|log| log.hash_key_override_status = Some("skipped"));
}
// Clone the request's hash_key_override before passing it to process_hash_key_override_if_needed
// since we also need it for the FlagEvaluationOverrides struct
let request_hash_key_override = hash_key_override.clone();
// Process any hash key overrides
let (hash_key_overrides, flag_hash_key_override_error) = self
.process_hash_key_override_if_needed(do_hash_key_lookup, hash_key_override)
.await;
let overrides = FlagEvaluationOverrides {
person_property_overrides,
group_property_overrides,
hash_key_overrides,
hash_key_override_error: flag_hash_key_override_error,
request_hash_key_override,
};
let flags_response = self
.evaluate_flags_with_overrides(
overrides,
request_id,
evaluation_stages,
flags_with_missing_deps,
)
.await?;
let has_errors = flag_hash_key_override_error
|| flags_response.errors_while_computing_flags
|| has_cycle_errors;
eval_timer
.label("outcome", if has_errors { "error" } else { "success" })
.fin();
Ok(FlagsResponse::new(
has_errors,
flags_response.flags,
None,
request_id,
))
}
/// Processes hash key overrides for feature flags with experience continuity enabled.
///
/// This method handles the logic for managing hash key overrides, which are used to ensure
/// consistent feature flag experiences across different distinct IDs (e.g., when a user logs in).
/// It performs the following steps:
///
/// 1. Checks if a hash key override needs to be written by comparing the current distinct ID
/// with the provided hash key
/// 2. If needed, writes the hash key override to the database using the writer connection
/// 3. Increments metrics to track successful/failed hash key override writes
/// 4. Retrieves and returns the current hash key overrides for the target distinct IDs
///
/// Returns a tuple containing:
/// - Option<HashMap<String, String>>: The hash key overrides if successfully retrieved, None if there was an error
/// - bool: Whether there was an error during processing (true = error occurred)
#[instrument(skip_all, fields(team_id = %self.team_id, distinct_id = %self.distinct_id))]
async fn process_hash_key_override(
&self,
hash_key: String,
target_distinct_ids: Vec<String>,
) -> (Option<HashMap<String, String>>, bool) {
let should_write = match before_persons_db_deadline(
self.persons_db_deadline,
db_operations::SHOULD_WRITE_HASH_KEY_OVERRIDE,
should_write_hash_key_override(
&self.router,
self.team_id,
self.distinct_id.clone(),
hash_key.clone(),
),
)
.await
{
Ok(should_write) => should_write,
Err(e) => {
error!(
"Failed to check if hash key override should be written for team {} distinct_id {}: {:?}",
self.team_id, self.distinct_id, e
);
inc(
FLAG_EVALUATION_ERROR_COUNTER,
&[("reason".to_string(), e.evaluation_error_code())],
1,
);
return (None, true);
}
};
let mut writing_hash_key_override = false;
if should_write {
if self.skip_writes {
tracing::debug!(
team_id = self.team_id,
distinct_id = %self.distinct_id,
"SKIP_WRITES: skipping hash key override write to PostgreSQL"
);
} else {
// NB: this is the only method that writes to the database
if let Err(e) = before_persons_db_deadline(
self.persons_db_deadline,
db_operations::SET_HASH_KEY_OVERRIDES,
set_feature_flag_hash_key_overrides(
&self.router,
self.team_id,
target_distinct_ids.clone(),
hash_key.clone(),
),
)
.await
{
error!("Failed to set feature flag hash key overrides for team {} distinct_id {} hash_key {}: {:?}", self.team_id, self.distinct_id, hash_key, e);
inc(
FLAG_EVALUATION_ERROR_COUNTER,
&[("reason".to_string(), e.evaluation_error_code())],
1,
);
return (None, true);
}
writing_hash_key_override = true;
}
}
inc(
FLAG_HASH_KEY_WRITES_COUNTER,
&[(
"successful_write".to_string(),
writing_hash_key_override.to_string(),
)],
1,
);
// When we're writing a hash_key_override, we query the main database (writer), not the replica (reader)
// This is because we need to make sure the write is successful before we read it back
// to avoid read-after-write consistency issues with database replication lag
let (database_for_reading, pool_name) = if writing_hash_key_override {
(
self.router.get_persons_writer().clone(),
pool_names::PERSONS_WRITER,
)
} else {
(
self.router.get_persons_reader().clone(),
pool_names::PERSONS_READER,
)
};
match before_persons_db_deadline(
self.persons_db_deadline,
db_operations::GET_HASH_KEY_OVERRIDES,
get_feature_flag_hash_key_overrides(
database_for_reading,
pool_name,
self.router.get_persons_writer().clone(),
self.team_id,
target_distinct_ids,
),
)
.await
{
Ok(overrides) => (Some(overrides), false),
Err(e) => {
error!("Failed to get feature flag hash key overrides for team {} distinct_id {}: {:?}", self.team_id, self.distinct_id, e);
inc(
FLAG_EVALUATION_ERROR_COUNTER,
&[("reason".to_string(), e.evaluation_error_code())],
1,
);
(None, true)
}
}
}
/// Evaluates cohort filters using cached membership results (both static and realtime)
/// and evaluates dynamic cohorts based on the provided properties.
pub fn evaluate_cohort_filters(
&self,
cohort_property_filters: &[&PropertyFilter],
target_properties: &HashMap<String, Value>,
cohorts: Arc<[Cohort]>,
) -> Result<bool, FlagError> {
// Track cohort evaluations in canonical log
with_canonical_log(|log| log.eval.cohorts_evaluated += cohort_property_filters.len());
let (cohort_matches, errors) =
self.resolve_cohort_matches(cohort_property_filters, target_properties, &cohorts);
if let Some(error) = errors.into_iter().next() {
return Err(error);
}
// Apply cohort membership logic (IN|NOT_IN) to the cohort match results
apply_cohort_membership_logic(cohort_property_filters, &cohort_matches)
}
/// Resolves every cohort the given filters reference to a membership boolean, starting from
/// the memberships cached during `prepare_flag_evaluation_state` (static and realtime).
fn resolve_cohort_matches(
&self,
cohort_property_filters: &[&PropertyFilter],
target_properties: &HashMap<String, Value>,
cohorts: &[Cohort],
) -> (HashMap<CohortId, bool>, Vec<FlagError>) {
// Get cached cohort results (static + realtime, merged during prepare_flag_evaluation_state)
let cached_matches = match self.flag_evaluation_state.get_cohort_matches() {
Some(matches) => matches.clone(),
None => HashMap::new(), // Happens when targeting an anonymous user with no person record
};
Self::resolve_cohort_matches_from_cache(
cohort_property_filters,
target_properties,
cohorts,
cached_matches,
PropertyMatchingContext::new(self.timezone, self.use_explicit_exact_matching),
)
}
/// Evaluates any dynamic cohort the filters reference that the cache does not already cover.
///
/// Resolution continues past a cohort that fails, and the failures come back alongside the
/// memberships that did resolve. A caller that must agree with the whole filter set fails on
/// the first error; condition analysis keeps what resolved, because a cohort left out of the
/// map reads as unknown rather than as a non-match. Both paths share this loop so a change to
/// cohort resolution cannot reach one and miss the other.
fn resolve_cohort_matches_from_cache(
cohort_property_filters: &[&PropertyFilter],
target_properties: &HashMap<String, Value>,
cohorts: &[Cohort],
cached_matches: HashMap<CohortId, bool>,
matching_context: PropertyMatchingContext,
) -> (HashMap<CohortId, bool>, Vec<FlagError>) {
let mut cohort_matches = cached_matches;
let mut errors = Vec::new();
// For any cohorts not yet evaluated (i.e., dynamic ones), evaluate them
for filter in cohort_property_filters {
let Some(cohort_id) = filter.get_cohort_id() else {
errors.push(FlagError::CohortFiltersParsingError);
continue;
};
if !cohort_matches.contains_key(&cohort_id) {
let current_matches = cohort_matches.clone();
match evaluate_dynamic_cohorts(
cohort_id,
target_properties,
cohorts,
¤t_matches,
matching_context,
) {
Ok(match_result) => {
cohort_matches.insert(cohort_id, match_result);
}
Err(error) => errors.push(error),
}
}
}
(cohort_matches, errors)
}
/// Resolves cohort memberships for every cohort filter on the flag, for detailed condition
/// analysis.
///
/// The evaluation state caches static and realtime memberships only, because
/// `evaluate_cohort_filters` discards the dynamic ones it resolves. Reading that cache alone
/// would report every dynamic cohort as a non-match.
fn cohort_matches_for_analysis(
&self,
flag: &FeatureFlag,
person_properties: Option<&HashMap<String, Value>>,
) -> HashMap<CohortId, CohortMembership> {
let cohort_filters: Vec<&PropertyFilter> = flag
.filters
.groups
.iter()
.filter_map(|group| group.properties.as_ref())
.flatten()
.filter(|filter| filter.is_cohort())
.collect();
if cohort_filters.is_empty() {
return HashMap::new();
}
let Some(cohorts) = self.flag_evaluation_state.cohorts.clone() else {
return HashMap::new();
};
let target_properties = person_properties.unwrap_or(&EMPTY_PROPERTY_MAP);
// A condition can name a cohort the flags payload no longer carries, because Django omits
// deleted and cross-team cohorts but keeps the filters that name them. Those failures stay
// out of the map, so the analysis reports them as unknown instead of as a non-match.
let (cohort_matches, errors) =
self.resolve_cohort_matches(&cohort_filters, target_properties, &cohorts);
for error in errors {
warn!("Cohort left unresolved for condition analysis: {error:?}");
}
// A non-match on a behavioral or lifecycle cohort is the dynamic path's default, not a
// checked answer, which is why the matcher reports it as `cohort_not_evaluated`.
cohort_matches
.into_iter()
.map(|(cohort_id, is_member)| {
let membership = if is_member {
CohortMembership::Member
} else if cohorts
.iter()
.any(|cohort| cohort.id == cohort_id && cohort.has_behavioral_condition())
{
CohortMembership::UnverifiedNonMember
} else {
CohortMembership::NonMember
};
(cohort_id, membership)
})
.collect()
}
/// Evaluates feature flags with property and hash key overrides.
///
/// Takes pre-computed evaluation stages which should already be filtered by flag_keys if needed.
/// The stages determine which flags are evaluated and in what order.
pub async fn evaluate_flags_with_overrides(
&mut self,
overrides: FlagEvaluationOverrides,
request_id: Uuid,
evaluation_stages: Vec<Vec<FeatureFlag>>,
flags_with_missing_deps: HashSet<i32>,
) -> Result<FlagsResponse, FlagError> {
let mut errors_while_computing_flags = overrides.hash_key_override_error;
let mut evaluated_flags_map = HashMap::new();
// Joining `filtered_out_flag_ids` pre-seeds the flag false below, like an inactive
// flag, so a dependent's `flag_evaluates_to: false` condition still resolves.
let mut unsupported_flag_ids: Vec<FeatureFlagId> = Vec::new();
for flag in evaluation_stages.iter().flatten() {
if self.filtered_out_flag_ids.contains(&flag.id) {
continue;
}
if let Err(error) = flag.filters.require_supported() {
evaluated_flags_map.insert(flag.key.clone(), failed_flag_details(flag, &error));
unsupported_flag_ids.push(flag.id);
}
}
if !unsupported_flag_ids.is_empty() {
errors_while_computing_flags = true;
self.filtered_out_flag_ids.extend(unsupported_flag_ids);
}
// Collect flags from evaluation stages for preparation steps
let flags: Vec<&FeatureFlag> = evaluation_stages
.iter()
.flatten()
.filter(|flag| flag.filters.is_supported())
.collect();
// Handle hash key override errors by creating error responses for flags that need experience continuity
if overrides.hash_key_override_error && overrides.hash_key_overrides.is_none() {
let hash_key_error = FlagError::HashKeyOverrideError;
for flag in flags.iter().filter(|flag| {
!self.filtered_out_flag_ids.contains(&flag.id)
&& flag.filters.is_v1()
&& flag.ensure_experience_continuity.unwrap_or(false)
}) {
evaluated_flags_map
.insert(flag.key.clone(), failed_flag_details(flag, &hash_key_error));
}
}
// Step 1: Initialize group type mappings if needed
errors_while_computing_flags |= self.initialize_group_type_mappings_if_needed(&flags).await;
// Step 2: Prepare evaluation state for flags requiring DB properties
let db_prep_errors = self
.prepare_evaluation_state_if_needed(
&flags,
&overrides.person_property_overrides,
&overrides.group_property_overrides,
&mut evaluated_flags_map,
)
.await;
errors_while_computing_flags |= db_prep_errors;
// Pre-seed filtered-out flags as false so dependency conditions like
// `flag_evaluates_to=false` can match against them.
for &flag_id in &self.filtered_out_flag_ids {
self.flag_evaluation_state
.add_flag_evaluation_result(flag_id, FlagValue::Boolean(false));
}
// Step 3: Evaluate flags stage by stage in dependency order
self.flag_evaluation_state.failed_flag_ids =
ids_of_failed_flags(evaluated_flags_map.values()).collect();
for stage in evaluation_stages {
let (level_evaluated_flags_map, level_errors) = self
.evaluate_flags_in_level(
stage,
&mut evaluated_flags_map,
&overrides.person_property_overrides,
&overrides.group_property_overrides,
&overrides.hash_key_overrides,
&overrides.request_hash_key_override,
&flags_with_missing_deps,
)
.await?;
errors_while_computing_flags |= level_errors;
if level_errors {
self.flag_evaluation_state
.failed_flag_ids
.extend(ids_of_failed_flags(level_evaluated_flags_map.values()));
}
evaluated_flags_map.extend(level_evaluated_flags_map);
}
Ok(FlagsResponse::new(
errors_while_computing_flags,
evaluated_flags_map,
None,
request_id,
))
}
/// Prepares evaluation state for flags that require database properties.
/// Returns true if there were errors during preparation.
#[instrument(skip_all, fields(team_id = %self.team_id, distinct_id = %self.distinct_id))]
async fn prepare_evaluation_state_if_needed(
&mut self,
flags: &[&FeatureFlag],
person_property_overrides: &Option<HashMap<String, Value>>,
group_property_overrides: &Option<HashMap<String, HashMap<String, Value>>>,
evaluated_flags_map: &mut HashMap<String, FlagDetails>,
) -> bool {
let flags_requiring_db_preparation = flags_require_db_preparation(
flags,
person_property_overrides
.as_ref()
.unwrap_or(&HashMap::new()),
&self.filtered_out_flag_ids,
&|filter, effective_aggregation| {
self.group_filter_needs_db_prep(
filter,
effective_aggregation,
group_property_overrides.as_ref(),
)
},
);
if flags_requiring_db_preparation.is_empty() || self.only_use_override_person_properties {
self.flag_evaluation_state.skip_person_properties();
return false;
}
with_canonical_log(|log| log.outcome_marks.mark_needs_persons());
match self
.prepare_flag_evaluation_state(flags_requiring_db_preparation.as_slice())
.await
{
Ok(_) => false,
Err(e) => {
self.handle_db_preparation_error(
&flags_requiring_db_preparation,
&e,
evaluated_flags_map,
);
true
}
}
}
/// Handles errors during database preparation by creating error responses for affected flags.
fn handle_db_preparation_error(
&self,
flags_requiring_db_preparation: &[&FeatureFlag],
error: &FlagError,
evaluated_flags_map: &mut HashMap<String, FlagDetails>,
) {
evaluated_flags_map.extend(
flags_requiring_db_preparation
.iter()
.map(|flag| (flag.key.clone(), failed_flag_details(flag, error))),
);
error!(
"Error preparing flag evaluation state for team {} distinct_id {}: {:?}",
self.team_id, self.distinct_id, error
);
let reason = error.evaluation_error_code();
inc(
FLAG_EVALUATION_ERROR_COUNTER,
&[("reason".to_string(), reason)],
1,
);
}
/// Evaluates a set of flags with a combination of property overrides and DB properties
///
/// This function is designed to be used as part of a level-based evaluation strategy
/// (e.g., Kahn's algorithm) for handling flag dependencies.
///
/// Dispatches between sequential and parallel evaluation based on flag count.
/// Sequential: borrows flags by reference (zero-copy).
/// Parallel: moves owned flags into a rayon task via oneshot channel.
#[allow(clippy::too_many_arguments)]
#[instrument(skip_all, fields(team_id = %self.team_id, distinct_id = %self.distinct_id))]
async fn evaluate_flags_in_level(
&mut self,
flags: Vec<FeatureFlag>,
evaluated_flags_map: &mut HashMap<String, FlagDetails>,
person_property_overrides: &Option<HashMap<String, Value>>,
group_property_overrides: &Option<HashMap<String, HashMap<String, Value>>>,
hash_key_overrides: &Option<HashMap<String, String>>,
request_hash_key_override: &Option<String>,
flags_with_missing_deps: &HashSet<i32>,
) -> Result<(HashMap<String, FlagDetails>, bool), FlagError> {
let mut errors_while_computing_flags = false;
let mut level_evaluated_flags_map = HashMap::new();
let flags_to_evaluate: Vec<FeatureFlag> = flags
.into_iter()
.filter(|flag| {
!flag.deleted
&& flag.active
&& !self.filtered_out_flag_ids.contains(&flag.id)
&& !evaluated_flags_map.contains_key(&flag.key)
})
.collect();
let eval_type = if flags_to_evaluate.len() >= self.parallel_eval_threshold {
EvaluationType::Parallel
} else {
EvaluationType::Sequential
};
// Record evaluation type in canonical log for E2E latency metrics.
// Skip if no flags to evaluate (all deleted, filtered out, or already evaluated) — lets the
// metric label stay None → "none" rather than incorrectly reporting Sequential.
if !flags_to_evaluate.is_empty() {
with_canonical_log(|log| {
log.evaluation_type = EvaluationType::promote(log.evaluation_type, eval_type);
});
}
let labels = [("evaluation_type".to_string(), eval_type.to_string())];
histogram(FLAG_BATCH_SIZE, &labels, flags_to_evaluate.len() as f64);
inc(FLAG_BATCH_EVALUATION_COUNTER, &labels, 1);
let _batch_timer = timing_guard(FLAG_BATCH_EVALUATION_TIME, &labels);
let flag_get_match_timer = timing_guard(FLAG_GET_MATCH_TIME, &[]);
match eval_type {
EvaluationType::Sequential => {
flags_to_evaluate.iter().for_each(|flag| {
let result = self.evaluate_single_flag(
flag,
person_property_overrides,
group_property_overrides,
flags_with_missing_deps,
hash_key_overrides,
request_hash_key_override,
);
self.process_flag_result(
flag,
&result,
&mut level_evaluated_flags_map,
&mut errors_while_computing_flags,
person_property_overrides,
group_property_overrides,
);
});
}
EvaluationType::Parallel => {
let results = self
.evaluate_batch_parallel(
flags_to_evaluate,
person_property_overrides,
group_property_overrides,
flags_with_missing_deps,
hash_key_overrides,
request_hash_key_override,
)
.await?;
for (flag, result) in &results {
self.process_flag_result(
flag,
result,
&mut level_evaluated_flags_map,
&mut errors_while_computing_flags,
person_property_overrides,
group_property_overrides,
);
}
}
}
flag_get_match_timer
.label(
"outcome",
if errors_while_computing_flags {
"error"
} else {
"success"
},
)
.fin();
Ok((level_evaluated_flags_map, errors_while_computing_flags))
}
/// Process a single flag evaluation result: update evaluation state, record metrics, and
/// insert into the level map.
fn process_flag_result(
&mut self,
flag: &FeatureFlag,
result: &Result<FeatureFlagMatch, FlagError>,
level_evaluated_flags_map: &mut HashMap<String, FlagDetails>,
errors_while_computing_flags: &mut bool,
person_property_overrides: &Option<HashMap<String, Value>>,
group_property_overrides: &Option<HashMap<String, HashMap<String, Value>>>,
) {
match result {
Ok(flag_match) => {
self.flag_evaluation_state
.add_flag_evaluation_result(flag.id, flag_match.get_flag_value());
let flag_details = if self.detailed_analysis {
// Use merged person properties (DB + overrides) for condition analysis
let merged_person_props = self
.get_person_properties(person_property_overrides.as_ref())
.ok();
// Merged group properties (DB + overrides, including the injected
// `$group_key`) keyed by group type index, so group-typed condition
// filters resolve against the group rather than the person.
let merged_group_props =
self.merged_group_properties_for_flag(flag, group_property_overrides);
let cohort_matches =
self.cohort_matches_for_analysis(flag, merged_person_props.as_ref());
FlagDetails::create_with_analysis(
flag,
flag_match,
true,
merged_person_props.as_ref(),
Some(&merged_group_props),
Some(&self.flag_evaluation_state.flag_evaluation_results),
Some(&self.flag_evaluation_state.failed_flag_ids),
Some(&cohort_matches),
PropertyMatchingContext::new(
self.timezone,
self.use_explicit_exact_matching,
),
)
} else {
FlagDetails::create(flag, flag_match)
};
level_evaluated_flags_map.insert(flag.key.clone(), flag_details);
}
Err(e) => {
*errors_while_computing_flags = true;
with_canonical_log(|log| log.flags_errored += 1);
match e {
FlagError::DependencyNotFound(dependency_type, dependency_id) => warn!(
"Feature flag '{}' targeting deleted {} with id {} for distinct_id '{}': {:?}",
flag.key, dependency_type, dependency_id, self.distinct_id, e
),
// The failed dependency already logged its own error.
FlagError::DependencyFailed(dependency_id) => debug!(
"Feature flag '{}' failed because dependency {} failed",
flag.key, dependency_id
),
// The group type lookup already logged or counted its own failure.
FlagError::GroupTypeLookupFailed(cause) => debug!(
"Feature flag '{}' failed because the group type lookup failed: {:?}",
flag.key, cause
),
_ => error!(
"Error evaluating feature flag '{}' for distinct_id '{}': {:?}",
flag.key, self.distinct_id, e
),
}
let reason = e.evaluation_error_code();
inc(
FLAG_EVALUATION_ERROR_COUNTER,
&[("reason".to_string(), reason)],
1,
);
level_evaluated_flags_map.insert(flag.key.clone(), failed_flag_details(flag, e));
}
}
}
/// Resolves group property overrides for a specific group type index by mapping
/// the index to the group type name and looking up the corresponding overrides.
fn resolve_group_overrides<'a>(
&self,
group_type_index: GroupTypeIndex,
group_property_overrides: Option<&'a HashMap<String, HashMap<String, Value>>>,
) -> Option<&'a HashMap<String, Value>> {
let mapping = self.group_type_mapping.mapping()?;
let index_to_type_map = mapping.group_indexes_to_types();
let group_type = index_to_type_map.get(&group_type_index)?;
let group_overrides = group_property_overrides?;
group_overrides.get(group_type)
}
/// Builds merged group properties (DB + overrides) keyed by group type index for
/// every group type the flag's conditions reference. Used by detailed condition
/// analysis so group-typed filters resolve against the group's properties (and the
/// `$group_key` injected into overrides) rather than the person's. Every referenced
/// group type index is included, backed by an empty map if no properties were found.
pub(crate) fn merged_group_properties_for_flag(
&self,
flag: &FeatureFlag,
group_property_overrides: &Option<HashMap<String, HashMap<String, Value>>>,
) -> HashMap<GroupTypeIndex, HashMap<String, Value>> {
let referenced_indexes: HashSet<GroupTypeIndex> = flag
.filters
.requirements()
.group_property_type_indexes
.into_iter()
.collect();
let mut merged = HashMap::new();
for gti in referenced_indexes {
let overrides = self.resolve_group_overrides(gti, group_property_overrides.as_ref());
merged.insert(
gti,
self.get_group_properties(gti, overrides)
.unwrap_or_default(),
);
}
merged
}
/// Pushes CPU-bound flag evaluation onto the Rayon pool via [`RayonDispatcher`],
/// so the calling Tokio worker thread is free to serve other requests while
/// evaluation runs. The dispatcher bounds how many batches can be in-flight
/// simultaneously, preventing unbounded queue growth and preserving per-batch
/// work-stealing parallelism.
async fn evaluate_batch_parallel(
&self,
flags_to_evaluate: Vec<FeatureFlag>,
person_property_overrides: &Option<HashMap<String, Value>>,
group_property_overrides: &Option<HashMap<String, HashMap<String, Value>>>,
flags_with_missing_deps: &HashSet<i32>,
hash_key_overrides: &Option<HashMap<String, String>>,
request_hash_key_override: &Option<String>,
) -> Result<Vec<(FeatureFlag, Result<FeatureFlagMatch, FlagError>)>, FlagError> {
let matcher = self.clone();
let missing_deps = flags_with_missing_deps.clone();
let person_overrides = person_property_overrides.clone();
let group_overrides = group_property_overrides.clone();
let hash_overrides = hash_key_overrides.clone();
let req_hash_override = request_hash_key_override.clone();
// Save lightweight snapshots before moving flags into rayon.
// If the rayon task panics, we use these to construct per-flag error results
// instead of silently dropping flags from the response.
let team_id = self.team_id;
let flag_snapshots: Vec<_> = flags_to_evaluate
.iter()
.map(FlagSnapshot::from_flag)
.collect();
// Each rayon thread accumulates evaluation counters in a thread-local
// FlagsCanonicalLogLine. After evaluation, the per-flag deltas are
// returned alongside each flag result and merged into the request's
// tokio task-local canonical log.
let work = move || {
flags_to_evaluate
.into_par_iter()
.map(|flag| {
let _guard = install_rayon_canonical_log();
let result = matcher.evaluate_single_flag(
&flag,
&person_overrides,
&group_overrides,
&missing_deps,
&hash_overrides,
&req_hash_override,
);
let delta = take_rayon_canonical_log();
(flag, result, delta)
})
.collect::<Vec<_>>()
};
let result = match &self.rayon_dispatcher {
Some(dispatcher) => dispatcher
.try_spawn(work)
.await
.map_err(|t| FlagError::RayonSemaphoreTimeout(t.waited.as_millis() as u64))?,
None => {
// Fallback for tests: unbounded dispatch (no semaphore).
let (tx, rx) = tokio::sync::oneshot::channel();
rayon::spawn(move || {
if let Ok(value) = std::panic::catch_unwind(std::panic::AssertUnwindSafe(work))
{
drop(tx.send(value));
}
});
rx.await.ok()
}
};
let results_with_deltas = result.unwrap_or_else(|| {
error!("Rayon parallel evaluation task was dropped (likely panicked)");
Self::build_panic_fallback(flag_snapshots, team_id)
.into_iter()
.map(|(flag, result)| (flag, result, None))
.collect()
});
Ok(results_with_deltas
.into_iter()
.map(|(flag, result, delta)| {
if let Some(delta) = delta {
with_canonical_log(|log| log.merge_rayon_delta(&delta));
}
(flag, result)
})
.collect())
}
/// Constructs per-flag error results from lightweight snapshots when the
/// rayon task panics and drops the oneshot sender.
fn build_panic_fallback(
snapshots: Vec<FlagSnapshot>,
team_id: TeamId,
) -> Vec<(FeatureFlag, Result<FeatureFlagMatch, FlagError>)> {
snapshots
.into_iter()
.map(|snapshot| {
let stub = FeatureFlag {
id: snapshot.id,
key: snapshot.key,
// Panic fallback can't compute experiment linkage; use the shared default.
has_experiment: default_has_experiment(),
active: true,
version: snapshot.version,
filters: FlagFilters {
non_v1: snapshot.non_v1,
..FlagFilters::default()
},
team_id,
name: None,
deleted: false,
ensure_experience_continuity: None,
evaluation_runtime: None,
evaluation_tags: None,
bucketing_identifier: None,
};
(stub, Err(FlagError::batch_evaluation_panicked()))
})
.collect()
}
fn evaluate_single_flag(
&self,
flag: &FeatureFlag,
person_property_overrides: &Option<HashMap<String, Value>>,
group_property_overrides: &Option<HashMap<String, HashMap<String, Value>>>,
flags_with_missing_deps: &HashSet<i32>,
hash_key_overrides: &Option<HashMap<String, String>>,
request_hash_key_override: &Option<String>,
) -> Result<FeatureFlagMatch, FlagError> {
if flags_with_missing_deps.contains(&flag.id) {
return Ok(FeatureFlagMatch::missing_dependency());
}
self.get_match(
flag,
person_property_overrides.as_ref(),
group_property_overrides.as_ref(),
hash_key_overrides.as_ref(),
request_hash_key_override,
)
}
/// Determines if a feature flag matches for the current context.
///
/// This method evaluates the conditions of a feature flag to determine if it should be enabled,
/// and if so, which variant (if any) should be applied. It follows these steps:
///
/// 1. Check if there's a valid hashed identifier for the flag.
/// 2. Evaluate any super conditions that might override normal conditions.
/// 3. Sort and evaluate each condition, prioritizing those with variant overrides.
/// 4. For each matching condition, determine the appropriate variant and payload.
/// 5. Return the result of the evaluation, including match status, variant, reason, and payload.
///
/// The method also keeps track of the highest priority match reason and index,
/// which are used even if no conditions ultimately match.
pub fn get_match(
&self,
flag: &FeatureFlag,
person_property_overrides: Option<&HashMap<String, Value>>,
group_property_overrides: Option<&HashMap<String, HashMap<String, Value>>>,
hash_key_overrides: Option<&HashMap<String, String>>,
request_hash_key_override: &Option<String>,
) -> Result<FeatureFlagMatch, FlagError> {
if let Some(config) = flag.filters.supported_v2() {
return self.get_match_v2(config, person_property_overrides);
}
flag.filters.require_v1()?;
// Seed with the lowest-priority "could not evaluate" reason so any real evaluation
// result outranks it via `get_highest_priority_match_evaluation`. NoGroupType is
// the floor: a pure-group flag whose only condition is skipped for missing context
// still surfaces NoGroupType, while a person condition that runs and reports
// NoConditionMatch or OutOfRolloutBound takes precedence in mixed-targeting flags.
let mut highest_match = FeatureFlagMatchReason::NoGroupType;
let mut highest_index = None;
let mut had_skipped_group_conditions = false;
let mut had_unevaluable_cohort_conditions = false;
// Lazily compute properties per aggregation type. Person and group properties are
// cached separately so conditions with different aggregation modes can share them.
let mut cached_person_properties: Option<HashMap<String, Value>> = None;
let mut cached_group_properties: HashMap<i32, HashMap<String, Value>> = HashMap::new();
// Evaluate feature enrollment (early access features) first.
// Enrollment is a person-level concept — always uses person properties, even for
// group-based flags.
if flag.filters.feature_enrollment == Some(true) {
let enrollment_key = FlagFilters::enrollment_key(&flag.key);
let person_properties = self.get_person_properties(person_property_overrides)?;
if let Some(v) = person_properties.get(&enrollment_key) {
let is_match = FlagFilters::is_enrolled(v);
let payload = self.get_matching_payload(None, flag);
return Ok(FeatureFlagMatch {
matches: is_match,
variant: None,
reason: FeatureFlagMatchReason::SuperConditionValue,
condition_index: Some(0),
payload,
evaluation_v2: None,
});
}
}
// Match for holdout condition
// TODO: Validate holdout variant should have 0% default rollout %?
// TODO: All this validation we need to do suggests the modelling is imperfect here. Carrying forward for now, we'll only enable
// in beta, and potentially rework representation before rolling out to everyone. Probably the problem is holdout groups are an
// experiment level concept that applies across experiments, and we are creating a feature flag level primitive to handle it.
// Validating things like the variant name is the same across all flags, rolled out to 0%, has the same correct conditions is a bit of
// a pain here. But I'm not sure if feature flags should indeed know all this info. It's fine for them to just work with what they're given.
if flag.filters.holdout.is_some() {
let (is_match, holdout_value, evaluation_reason) =
self.is_holdout_condition_match(flag, request_hash_key_override)?;
if is_match {
let payload = self.get_matching_payload(holdout_value.as_deref(), flag);
return Ok(FeatureFlagMatch {
matches: true,
variant: holdout_value,
reason: evaluation_reason,
condition_index: None,
payload,
evaluation_v2: None,
});
}
}
let conditions: Vec<(usize, &FlagPropertyGroup)> =
flag.get_conditions().iter().enumerate().collect();
let early_exit_enabled = flag.filters.early_exit.unwrap_or(false);
// A condition on a failed flag cannot settle the answer. Each such condition records the
// answer the flag would give if the failed flag matched it. The flag fails only when one
// of those answers differs from the answer from its other conditions. Server SDKs read
// `failed: true` as false. Failing every dependent would therefore turn a settled `true`
// into false.
let mut answers_if_dependency_matched: Vec<AnswerIfDependencyMatched> = Vec::new();
// A later condition that matches still settles the flag. The skipped condition could
// have picked a different variant. With early exit, a skipped condition below 100%
// rollout could instead stop evaluation with no match, so a later match cannot settle
// the flag.
let mut group_lookup_error: Option<Arc<FlagError>> = None;
let mut group_lookup_skip_can_exit_early = false;
// The handler copies every request group key into the overrides as `$group_key`, also an
// unusable one. An override map with only an unusable `$group_key` therefore names no group.
let request_has_group_context = self.request_has_usable_group_key()
|| group_property_overrides.is_some_and(|overrides| {
overrides
.values()
.flatten()
.any(|(key, value)| key != "$group_key" || is_usable_group_key(value))
});
let condition_timer = common_metrics::timing_guard(FLAG_EVALUATE_ALL_CONDITIONS_TIME, &[]);
for (index, condition) in conditions {
// Each condition resolves its own aggregation, falling back to the flag-level
// value for backwards compatibility with flags that predate per-condition aggregation.
let aggregation = condition.effective_aggregation(flag.get_group_type_index());
// Device_id bucketing only applies to person-aggregated conditions. For mixed
// flags, group-aggregated conditions can still match even without a device_id.
if aggregation.is_none() {
use crate::flags::flag_models::BucketingIdentifier;
let buckets_on_device_id =
flag.get_bucketing_identifier() == BucketingIdentifier::DeviceId;
let has_device_id = self
.device_id
.as_ref()
.is_some_and(|device_id| !device_id.is_empty());
// Without a device_id there is nothing to bucket on, so the condition is
// withheld rather than bucketed on the wrong identifier. Withholding a
// condition whose outcome the hash cannot change would instead disable the
// flag for everyone it targets, so the guard asks whether it can.
if buckets_on_device_id
&& !has_device_id
&& flag.condition_needs_bucketing_hash(condition)
{
inc(
FLAG_CONDITION_SKIPPED_COUNTER,
&[("reason".to_string(), "missing_device_id".to_string())],
1,
);
with_canonical_log(|log| {
tracing::debug!(
flag_key = %flag.key,
team_id = %flag.team_id,
condition_index = %index,
lib = log.lib.as_deref(),
lib_version = log.lib_version.as_deref(),
"Person condition uses device_id bucketing but no device_id provided, skipping"
);
});
let (new_highest_match, new_highest_index) = self
.get_highest_priority_match_evaluation(
highest_match.clone(),
highest_index,
FeatureFlagMatchReason::OutOfRolloutBound,
Some(index),
);
highest_match = new_highest_match;
highest_index = new_highest_index;
continue;
}
if buckets_on_device_id && has_device_id {
with_canonical_log(|log| log.eval.flags_device_id_bucketing += 1);
}
}
if let Some(error) =
self.group_lookup_error_for(condition, aggregation, request_has_group_context)
{
inc(
FLAG_CONDITION_SKIPPED_COUNTER,
&[("reason".to_string(), "group_type_lookup_failed".to_string())],
1,
);
group_lookup_skip_can_exit_early |=
early_exit_enabled && condition.rollout_percentage_unwrapped() < 100.0;
group_lookup_error = Some(error);
continue;
}
// For group-aggregated conditions, verify we have the group key. If not, this
// condition can't match — log a warning and continue to the next condition.
// This checks the group key directly rather than calling hashed_identifier,
// which will be called again later in check_rollout/get_matching_variant.
if let Some(group_type_index) = aggregation {
if !self.has_group_key(group_type_index) {
inc(
FLAG_CONDITION_SKIPPED_COUNTER,
&[("reason".to_string(), "missing_group_type".to_string())],
1,
);
debug!(
flag_key = %flag.key,
team_id = %flag.team_id,
condition_index = %index,
"Condition uses group aggregation but group type not provided in evaluation context, skipping"
);
// Record this as a NoGroupType reason but continue to next condition.
// Track that we skipped a group condition so the final result can
// surface a richer description when person conditions also didn't match.
had_skipped_group_conditions = true;
let (new_highest_match, new_highest_index) = self
.get_highest_priority_match_evaluation(
highest_match.clone(),
highest_index,
FeatureFlagMatchReason::NoGroupType,
Some(index),
);
highest_match = new_highest_match;
highest_index = new_highest_index;
continue;
}
}
// Lazily compute properties based on what the condition's filters reference.
// A condition may have person filters, group filters, or both (mixed targeting).
// Properties are cached per type so conditions sharing a property source reuse them.
if Self::condition_needs_properties(condition) {
let (needs_person, needed_group_types) =
Self::condition_property_type_needs(condition, aggregation);
if needs_person && cached_person_properties.is_none() {
cached_person_properties =
Some(self.get_person_properties(person_property_overrides)?);
}
for >i in &needed_group_types {
if let std::collections::hash_map::Entry::Vacant(e) =
cached_group_properties.entry(gti)
{
let group_overrides =
self.resolve_group_overrides(gti, group_property_overrides);
let group_props = self.get_group_properties(gti, group_overrides)?;
e.insert(group_props);
}
}
}
let property_context = PropertyContext {
person_properties: cached_person_properties.as_ref(),
group_properties: &cached_group_properties,
aggregation,
request_has_group_context,
};
let (is_match, reason) = self.is_condition_match(
flag,
condition,
&property_context,
hash_key_overrides,
request_hash_key_override,
)?;
if reason == FeatureFlagMatchReason::NoConditionMatchCohortNotEvaluated {
had_unevaluable_cohort_conditions = true;
}
let failed_dependency = condition
.properties
.iter()
.flatten()
.find_map(|filter| self.flag_evaluation_state.failed_dependency(filter));
// OutOfRolloutBound means the condition's property filters (if any) already
// matched and only the rollout check failed, so re-evaluating later groups
// can't change the outcome.
if early_exit_enabled
&& !is_match
&& reason == FeatureFlagMatchReason::OutOfRolloutBound
{
// If the failed flag matched, the flag would stop here with no match.
// Otherwise the later conditions decide.
if let Some(failed_dependency) = failed_dependency {
answers_if_dependency_matched.push(AnswerIfDependencyMatched {
failed_dependency,
answer: ConditionAnswer::NoMatch,
});
} else {
if let Some(error) = self.no_match_error(
flag,
&answers_if_dependency_matched,
group_lookup_error,
) {
return Err(error);
}
return Ok(FeatureFlagMatch {
matches: false,
variant: None,
reason: FeatureFlagMatchReason::OutOfRolloutBound,
condition_index: Some(index),
payload: None,
evaluation_v2: None,
});
}
}
if is_match {
if let Some(failed_dependency) = failed_dependency {
let variant = self.condition_variant(
flag,
condition,
aggregation,
hash_key_overrides,
request_hash_key_override,
)?;
answers_if_dependency_matched.push(AnswerIfDependencyMatched {
failed_dependency,
answer: ConditionAnswer::Match(variant),
});
continue;
}
}
// Update highest_match and highest_index
let (new_highest_match, new_highest_index) = self
.get_highest_priority_match_evaluation(
highest_match.clone(),
highest_index,
reason.clone(),
Some(index),
);
highest_match = new_highest_match;
highest_index = new_highest_index;
if is_match {
let variant = self.condition_variant(
flag,
condition,
aggregation,
hash_key_overrides,
request_hash_key_override,
)?;
if !answers_if_dependency_matched.is_empty() {
if let Some(dependency) = self.dependency_that_changes_answer(
flag,
&answers_if_dependency_matched,
&ConditionAnswer::Match(variant.clone()),
) {
return Err(FlagError::DependencyFailed(dependency.into()));
}
}
if let Some(error) = group_lookup_error.filter(|_| group_lookup_skip_can_exit_early)
{
return Err(FlagError::GroupTypeLookupFailed(error));
}
let payload = self.get_matching_payload(variant.as_deref(), flag);
return Ok(FeatureFlagMatch {
matches: true,
variant,
reason: highest_match,
condition_index: highest_index,
payload,
evaluation_v2: None,
});
}
}
if let Some(error) =
self.no_match_error(flag, &answers_if_dependency_matched, group_lookup_error)
{
return Err(error);
}
condition_timer.label("outcome", "success").fin();
// When person conditions were evaluated (and didn't match) but group conditions
// were skipped because the caller didn't provide the required group type, upgrade
// the reason to carry a richer description. The API code still serializes as
// "no_condition_match" for backward compatibility, but the description tells the
// caller about the skipped group conditions.
// A cohort that can't be fully evaluated takes precedence over a skipped group
// condition, because it reaches real flag traffic.
if highest_match == FeatureFlagMatchReason::NoConditionMatch {
if had_unevaluable_cohort_conditions {
highest_match = FeatureFlagMatchReason::NoConditionMatchCohortNotEvaluated;
} else if had_skipped_group_conditions {
highest_match = FeatureFlagMatchReason::NoConditionMatchGroupsNotEvaluated;
}
}
// Return with the highest_match reason and index even if no conditions matched
Ok(FeatureFlagMatch {
matches: false,
variant: None,
reason: highest_match,
condition_index: highest_index,
payload: None,
evaluation_v2: None,
})
}
/// Projects a v2 outcome onto the v1 match shape: a null value is disabled, a boolean is
/// `enabled`, a string is the variant, and a number or object is an enabled flag whose value
/// travels as a JSON-encoded payload, like a v1 payload. The subject is the request distinct ID.
fn get_match_v2(
&self,
config: &Config,
person_property_overrides: Option<&HashMap<String, Value>>,
) -> Result<FeatureFlagMatch, FlagError> {
// A config without predicates never reads properties, so skip the merge.
let merged = if config.rules.iter().any(|rule| !rule.targeting.is_empty()) {
Some(self.get_person_properties(person_property_overrides)?)
} else {
None
};
// An overrides-only request treats its map as authoritative, as v1 does.
let properties = match &merged {
Some(map)
if self.only_use_override_person_properties
|| self.flag_evaluation_state.get_person_properties().is_some() =>
{
PersonProperties::Complete(map)
}
Some(map) if person_property_overrides.is_some() => PersonProperties::Partial(map),
_ => PersonProperties::Unavailable,
};
let evaluation = Evaluator::new(config).evaluate(&EvaluationContext {
person_identifier: &self.distinct_id,
properties,
timezone: self.timezone,
use_explicit_exact_matching: self.use_explicit_exact_matching,
now: self.now,
})?;
// `/flags?v=2` reports these v1 reasons; `/flags?v=4` reports the evaluator's own code.
let reason = match evaluation {
Evaluation::TargetingMatch { .. } | Evaluation::ExperimentSplit { .. } => {
FeatureFlagMatchReason::ConditionMatch
}
Evaluation::RolloutMiss { .. } => FeatureFlagMatchReason::OutOfRolloutBound,
Evaluation::Holdout { .. } => FeatureFlagMatchReason::HoldoutConditionValue,
Evaluation::ExperimentPaused { .. } | Evaluation::NoRuleMatch { .. } => {
FeatureFlagMatchReason::NoConditionMatch
}
};
let condition_index = evaluation.rule().map(|rule| rule.index);
let (matches, variant, payload) = match evaluation.value() {
None => (false, None, None),
Some(Value::Bool(value)) => (*value, None, None),
Some(Value::String(value)) => (true, Some(value.clone()), None),
Some(value) => (true, None, Some(Value::String(value.to_string()))),
};
Ok(FeatureFlagMatch {
matches,
variant,
reason,
condition_index,
payload,
evaluation_v2: Some(evaluation.into()),
})
}
fn dependency_that_changes_answer(
&self,
flag: &FeatureFlag,
answers_if_dependency_matched: &[AnswerIfDependencyMatched],
answer: &ConditionAnswer,
) -> Option<FeatureFlagId> {
let compare_variants = !self.enabled_only_flag_keys.contains(&flag.key);
answers_if_dependency_matched
.iter()
.find(|candidate| {
if compare_variants {
candidate.answer != *answer
} else {
candidate.answer.is_match() != answer.is_match()
}
})
.map(|candidate| candidate.failed_dependency)
}
fn no_match_error(
&self,
flag: &FeatureFlag,
answers_if_dependency_matched: &[AnswerIfDependencyMatched],
group_lookup_error: Option<Arc<FlagError>>,
) -> Option<FlagError> {
self.dependency_that_changes_answer(
flag,
answers_if_dependency_matched,
&ConditionAnswer::NoMatch,
)
.map(|dependency| FlagError::DependencyFailed(dependency.into()))
.or_else(|| group_lookup_error.map(FlagError::GroupTypeLookupFailed))
}
/// This function determines the highest priority match evaluation for feature flag conditions.
/// It compares the current match reason with a new match reason and returns the higher priority one.
/// The priority is determined by the ordering of FeatureFlagMatchReason variants.
/// It's used to keep track of the most significant reason why a flag matched or didn't match,
/// especially useful when multiple conditions are evaluated.
fn get_highest_priority_match_evaluation(
&self,
current_match: FeatureFlagMatchReason,
current_index: Option<usize>,
new_match: FeatureFlagMatchReason,
new_index: Option<usize>,
) -> (FeatureFlagMatchReason, Option<usize>) {
if current_match <= new_match {
(new_match, new_index)
} else {
(current_match, current_index)
}
}
/// Check if a condition matches for a feature flag.
///
/// Evaluates a specific condition to determine if it should be enabled.
/// If the condition has no property filters, performs a rollout check only.
/// Otherwise, checks if the provided properties satisfy the condition's filters.
///
/// Each filter is matched against the correct property source based on its type:
/// person filters use person properties, group filters use the group properties
/// for that filter's `group_type_index`. This enables mixed targeting where a
/// single condition combines person and group filters with independent rollout.
pub(crate) fn is_condition_match(
&self,
feature_flag: &FeatureFlag,
condition: &FlagPropertyGroup,
property_context: &PropertyContext,
hash_key_overrides: Option<&HashMap<String, String>>,
request_hash_key_override: &Option<String>,
) -> Result<(bool, FeatureFlagMatchReason), FlagError> {
let rollout_percentage = condition.rollout_percentage.unwrap_or(100.0);
if let Some(flag_property_filters) = &condition.properties {
if flag_property_filters.is_empty() {
return self.check_rollout(
feature_flag,
rollout_percentage,
property_context.aggregation,
hash_key_overrides,
request_hash_key_override,
);
}
if self
.flag_evaluation_state
.failed_dependency_filters_conflict(flag_property_filters)
{
return Ok((false, FeatureFlagMatchReason::NoConditionMatch));
}
// Single-pass evaluation: flag-value and property filters are evaluated in Vec order
// and short-circuit immediately on mismatch. Cohort filters (the most expensive)
// are deferred and batch-evaluated after the loop to avoid unnecessary work.
let mut cohort_filters: Vec<&PropertyFilter> = Vec::new();
for filter in flag_property_filters {
if filter.depends_on_feature_flag() {
// A filter on a flag that failed earlier in this request passes here, so the
// other filters and the rollout still decide whether the condition can
// match. `get_match` uses such a match only as the answer the flag would give
// if the failed flag matched.
if self
.flag_evaluation_state
.failed_dependency(filter)
.is_some()
{
continue;
}
if !match_flag_value_to_flag_filter(
filter,
&self.flag_evaluation_state.flag_evaluation_results,
) {
return Ok((false, FeatureFlagMatchReason::NoConditionMatch));
}
} else if filter.is_cohort() {
cohort_filters.push(filter);
} else {
let props = property_context.resolve_for_filter(filter);
// Person properties that were never fetched (DB prep didn't run for this
// evaluation) must not be treated as "person has no properties", because
// an absent key would then make negative operators (is_not, not_icontains,
// ...) and is_not_set match by accident. partial_props makes match_property
// error on a missing key instead of matching it; the unwrap_or(false) below
// turns that error into no-match, so the condition fails closed. Only
// Pending gets this: Skipped and Fetched property maps are authoritative,
// so an absent key there genuinely means the person lacks the property.
// This is defense in depth: in the batch flow a prep failure errors those
// flags out before evaluation, so the guard protects any path that reaches
// evaluation with the state still Pending. Cohort filters get the same
// treatment below, refusing to evaluate outright since cohort membership
// is unknowable under Pending. Group filters get the equivalent guard
// keyed on their own group type — see `filter_needs_partial_props`.
let partial_props = self.filter_needs_partial_props(filter, property_context);
if !match_property(
filter,
props,
partial_props,
PropertyMatchingContext::new(
self.timezone,
self.use_explicit_exact_matching,
),
)
.unwrap_or(false)
{
return Ok((false, FeatureFlagMatchReason::NoConditionMatch));
}
}
}
// Evaluate cohort filters using person properties (cohorts are person-level).
if !cohort_filters.is_empty() {
// Cohort evaluation reads the same person-property map as direct filters, and
// both the property-level `negation` inside a cohort definition and cohort-level
// NOT_IN would turn a missing key into a match. Membership is unknowable under
// Pending either way, so refuse to evaluate rather than guess. Today no prep path
// loads cohorts without fetching person properties, so this should be unreachable
// — hence the error log, which flags a broken invariant rather than normal traffic.
if self.flag_evaluation_state.person_properties_pending() {
inc(
PROPERTY_CACHE_MISSES_COUNTER,
&[
("type".to_string(), "cohort_filters".to_string()),
("reason".to_string(), "db_prep_never_ran".to_string()),
],
1,
);
with_canonical_log(|log| {
log.eval.property_cache_misses += 1;
log.eval.person_properties_not_cached = true;
});
tracing::error!(
"Cohort filters not evaluated — DB prep never ran, so the condition fails closed"
);
return Ok((false, FeatureFlagMatchReason::NoConditionMatch));
}
let cohorts = match &self.flag_evaluation_state.cohorts {
Some(cohorts) => cohorts.clone(),
None => return Ok((false, FeatureFlagMatchReason::NoConditionMatch)),
};
let cohort_props = property_context
.person_properties
.unwrap_or(&*EMPTY_PROPERTY_MAP);
if !self.evaluate_cohort_filters(&cohort_filters, cohort_props, cohorts.clone())? {
// A non-match isn't trustworthy when a targeted cohort has a behavioral or
// lifecycle leaf the dynamic path can't resolve, so flag it with a distinct reason.
// An operator the matcher does not honor fails the condition whatever the
// membership is, so the caveat does not hold for one of those.
let cohort_membership_unresolved = cohort_filters
.iter()
.all(|filter| filter.cohort_operator_is_supported())
&& cohort_filters.iter().any(|filter| {
filter.get_cohort_id().is_some_and(|cohort_id| {
cohorts
.iter()
.any(|c| c.id == cohort_id && c.has_behavioral_condition())
})
});
let reason = if cohort_membership_unresolved {
FeatureFlagMatchReason::NoConditionMatchCohortNotEvaluated
} else {
FeatureFlagMatchReason::NoConditionMatch
};
return Ok((false, reason));
}
}
}
self.check_rollout(
feature_flag,
rollout_percentage,
property_context.aggregation,
hash_key_overrides,
request_hash_key_override,
)
}
/// Seeds the mapping that `initialize_group_type_mappings_if_needed` loads in production,
/// for tests that exercise matching without running DB prep.
#[cfg(test)]
pub(crate) fn set_group_type_mapping_for_test(&mut self, mapping: GroupTypeMapping) {
self.group_type_mapping = GroupTypeMappingState::Loaded(mapping);
}
#[cfg(test)]
pub(crate) fn set_group_type_mapping_failed_for_test(&mut self, error: FlagError) {
self.group_type_mapping = GroupTypeMappingState::Failed(Arc::new(error));
}
/// Whether the request supplied a usable group key for this group type name. Without one
/// there is no group to load properties for, so group filters on that type have no
/// context at all — distinct from having a key whose properties weren't fetched.
fn has_usable_group_key(&self, group_type: &str) -> bool {
self.groups.get(group_type).is_some_and(is_usable_group_key)
}
/// `has_usable_group_key` by group type index. False both when the request omitted the
/// group and when the mapping can't resolve the index, so callers that must tell those
/// apart resolve the name themselves — see `filter_needs_partial_props`.
fn has_group_key(&self, group_type_index: GroupTypeIndex) -> bool {
self.group_type_mapping
.mapping()
.and_then(|m| m.group_indexes_to_types().get(&group_type_index))
.is_some_and(|group_type| self.has_usable_group_key(group_type))
}
fn request_has_usable_group_key(&self) -> bool {
self.groups.values().any(is_usable_group_key)
}
/// A condition names its group type by index. Only the mapping tells which group key or
/// group property override in the request has that index. A request without them gets
/// the same answer under any mapping, so its conditions evaluate as usual.
fn group_lookup_error_for(
&self,
condition: &FlagPropertyGroup,
aggregation: Option<GroupTypeIndex>,
request_has_group_context: bool,
) -> Option<Arc<FlagError>> {
let GroupTypeMappingState::Failed(error) = &self.group_type_mapping else {
return None;
};
// A group-aggregated condition hashes the group key, so a request without a usable
// key gets no match from it under any mapping, even when it sends property overrides.
let outcome_unknown = if aggregation.is_some() {
self.request_has_usable_group_key()
} else {
request_has_group_context
&& condition
.properties
.iter()
.flatten()
.any(|filter| filter.group_filter_index(None).is_some())
};
outcome_unknown.then(|| Arc::clone(error))
}
/// Whether DB preparation would load anything this group filter can use. Selecting a
/// filter pulls its whole flag into preparation, and with it the person-property query,
/// so a filter only counts when the fetch can serve it: the mapping resolves its index,
/// the request carries a usable key for that group type, and no group property override
/// already supplies the filtered key. In every other state the fetch would load nothing
/// for the filter, and matching handles those states itself — see
/// `filter_needs_partial_props`.
fn group_filter_needs_db_prep(
&self,
filter: &PropertyFilter,
effective_aggregation: Option<GroupTypeIndex>,
group_property_overrides: Option<&HashMap<String, HashMap<String, Value>>>,
) -> bool {
let Some(gti) = filter.group_filter_index(effective_aggregation) else {
return false;
};
let Some(group_type) = self
.group_type_mapping
.mapping()
.and_then(|m| m.group_indexes_to_types().get(>i))
else {
return false;
};
if !self.has_usable_group_key(group_type) {
return false;
}
!group_property_overrides
.and_then(|overrides| overrides.get(group_type))
.is_some_and(|group_overrides| group_overrides.contains_key(&filter.key))
}
/// Whether a filter must be matched with `partial_props`, i.e. treat an absent key as
/// "unknown" (an error, which the caller turns into no-match) rather than as
/// "the property is not set" (which would make negative operators match by accident).
///
/// This is only true when the relevant property source was never fetched. Fetched and
/// deliberately-skipped property maps are authoritative, so an absent key there
/// genuinely means the property is unset.
fn filter_needs_partial_props(
&self,
filter: &PropertyFilter,
property_context: &PropertyContext,
) -> bool {
if filter.prop_type != PropertyType::Group {
return self.flag_evaluation_state.person_properties_pending();
}
// A group filter with no resolvable group type index can't be routed to a group
// property map at all, so there is nothing to fail closed on.
let Some(gti) = filter.group_filter_index(property_context.aggregation) else {
return false;
};
// This check comes before the name lookup, so a failed or stale mapping does not change
// the answer for a request without group context.
if !property_context.request_has_group_context {
return false;
}
// Without a resolved name for the index, nothing is known about the group: the
// lookup failed, or a loaded mapping predates the group type (a stale cache entry).
// The request may carry this very group under the name that can't be resolved, so
// this must not read as "no group context" — fail closed.
let Some(group_type) = self
.group_type_mapping
.mapping()
.and_then(|m| m.group_indexes_to_types().get(>i))
else {
return true;
};
// No group key means no group context whatsoever — the request never claimed to be
// in a group of this type. Failing closed there would silently stop matching for
// every caller that doesn't send `groups`, which is a much broader behavior change
// than the fetch-miss this guard is for, so keep the existing semantics.
if !self.has_usable_group_key(group_type) {
return false;
}
self.flag_evaluation_state.group_properties_pending(gti)
}
/// Checks if a condition requires person/group properties to evaluate.
/// Returns false for rollout-only conditions or conditions with only flag-value filters.
fn condition_needs_properties(condition: &FlagPropertyGroup) -> bool {
condition.properties.as_ref().is_some_and(|props| {
// Check if there are any non-flag-value property filters
props.iter().any(|prop| !prop.depends_on_feature_flag())
})
}
/// Determines which property sources a condition's filters reference.
/// Returns (needs_person_properties, set_of_group_type_indexes_needed).
fn condition_property_type_needs(
condition: &FlagPropertyGroup,
effective_aggregation: Option<GroupTypeIndex>,
) -> (bool, HashSet<i32>) {
let mut needs_person = false;
let mut group_types = HashSet::new();
if let Some(props) = &condition.properties {
for prop in props {
if prop.depends_on_feature_flag() || prop.is_cohort() {
// Cohort filters are evaluated against person properties, so the
// caller must load them before constructing the PropertyContext.
// Flag filters don't need any properties.
if prop.is_cohort() {
needs_person = true;
}
continue;
}
match prop.prop_type {
PropertyType::Person | PropertyType::PersonMetadata => needs_person = true,
PropertyType::Group => {
if let Some(gti) = prop.group_filter_index(effective_aggregation) {
group_types.insert(gti);
}
}
// Cohort and Flag filters are handled by the guard above, but
// listing them explicitly ensures a compile error if a new
// PropertyType variant is added.
PropertyType::Cohort | PropertyType::Flag => {}
}
}
}
// For legacy flags where all filters lack explicit types but the condition
// is group-aggregated, ensure the aggregation index is included. Similarly,
// person-aggregated legacy conditions need person properties loaded.
if group_types.is_empty() && !needs_person {
match effective_aggregation {
Some(gti) => {
group_types.insert(gti);
}
None => needs_person = true,
}
}
(needs_person, group_types)
}
/// Gets group properties by merging DB properties with overrides (overrides take precedence).
fn get_group_properties(
&self,
group_type_index: GroupTypeIndex,
property_overrides: Option<&HashMap<String, Value>>,
) -> Result<HashMap<String, Value>, FlagError> {
// Start with DB properties
let mut merged_properties =
self.get_group_properties_from_evaluation_state(group_type_index)?;
// Merge in overrides (overrides take precedence)
if let Some(overrides) = property_overrides {
merged_properties.extend(overrides.iter_owned());
}
// Return all merged properties
Ok(merged_properties)
}
/// Gets person properties by merging DB properties with overrides (overrides take precedence).
fn get_person_properties(
&self,
property_overrides: Option<&HashMap<String, Value>>,
) -> Result<HashMap<String, Value>, FlagError> {
let mut merged_properties = if self.only_use_override_person_properties {
// When only_use_override_person_properties is true, ignore DB properties entirely
HashMap::new()
} else {
// Start with DB properties (clone only when we need a mutable copy)
self.get_person_properties_from_evaluation_state()
.cloned()
.unwrap_or_default()
};
// Merge in overrides (overrides take precedence).
//
// PersonMetadata fields are stored under sentinel-prefixed keys (see
// `lookup_key_for` in property_matching.rs). A caller could override the canonical
// persons-table value by setting that sentinel key in `person_property_overrides`.
// That's intentional for testing — no SDK has any reason to set such a key in
// production, and overrides are caller-trusted by design. If we ever need to lock
// metadata fields to the DB value, filter the prefixed keys out here.
if let Some(overrides) = property_overrides {
merged_properties.extend(overrides.iter_owned());
}
// Mirror $os <-> $os_name so a condition keyed on either matches when the
// person row carries only one of them (web reports $os, mobile $os_name).
// Runs before initial-property population so an aliased $os can backfill $initial_os.
populate_os_aliases(&mut merged_properties);
// Populate missing $initial_ properties from their non-initial counterparts.
// DB $initial_ values are preserved; this only fills in missing ones from
// the merged properties (which may come from DB or request overrides).
populate_missing_initial_properties(&mut merged_properties);
Ok(merged_properties)
}
fn is_holdout_condition_match(
&self,
flag: &FeatureFlag,
request_hash_key_override: &Option<String>,
) -> Result<(bool, Option<String>, FeatureFlagMatchReason), FlagError> {
if let Some(holdout) = &flag.filters.holdout {
let percentage = holdout.exclusion_percentage_clamped();
if !crate::flags::v1_bucketing::is_in_rollout(percentage, || {
self.get_holdout_hash(flag, None, request_hash_key_override)
})? {
// User's hash is above the exclusion threshold — not in holdout
return Ok((false, None, FeatureFlagMatchReason::OutOfRolloutBound));
}
// User is in holdout — variant name is derived from the holdout id
return Ok((
true,
Some(format!("holdout-{}", holdout.id)),
FeatureFlagMatchReason::HoldoutConditionValue,
));
}
Ok((false, None, FeatureFlagMatchReason::NoConditionMatch))
}
/// Get hashed identifier for flag evaluation.
///
/// Resolves the identifier used for hashing (rollout and variant assignment) based on
/// the provided aggregation group type index. For group-based aggregation, uses the
/// group key; for person-based aggregation, uses the distinct_id (with experience
/// continuity and device_id bucketing fallbacks).
///
/// For person-based flags with ensure_experience_continuity enabled, the identifier priority is:
/// 1. DB-stored hash_key_override (for consistency across sessions)
/// 2. Request's hash_key_override (anon_distinct_id) for first-time evaluations
/// 3. distinct_id (final fallback)
fn hashed_identifier(
&self,
feature_flag: &FeatureFlag,
aggregation_group_type_index: Option<i32>,
hash_key_overrides: Option<&HashMap<String, String>>,
request_hash_key_override: &Option<String>,
) -> Result<String, FlagError> {
if let Some(group_type_index) = aggregation_group_type_index {
// Group-based flag
let group_key = match self.group_type_mapping.mapping().and_then(|m| {
m.group_indexes_to_types()
.get(&group_type_index)
.and_then(|group_type_name| self.groups.get(group_type_name))
}) {
Some(Value::String(s)) => s.clone(),
Some(Value::Number(n)) => n.to_string(),
Some(_) => {
// For any other JSON type (bool, array, object, null), use empty string
// NB: we currently use empty string ("") as the hashed identifier for group flags without a group key,
// and I don't want to break parity with the old service since I don't want the hash values to change
"".to_string()
}
None => "".to_string(),
};
Ok(group_key)
} else {
// Person-based flag
use crate::flags::flag_models::BucketingIdentifier;
// Check if flag is configured for device_id bucketing
if feature_flag.get_bucketing_identifier() == BucketingIdentifier::DeviceId {
if let Some(device_id) = &self.device_id {
if !device_id.is_empty() {
return Ok(device_id.clone());
}
}
}
// Use hash key overrides for experience continuity. Only consult overrides
// when the flag *currently* has continuity enabled — a stored override row
// is never deleted when continuity is turned off, so a stale row must not
// steer a flag whose continuity is now off (which would keep every distinct_id
// of the person bucketing on the old key).
// Priority: DB override > request's anon_distinct_id > distinct_id
if feature_flag.has_experience_continuity() {
if let Some(hash_key_override) = hash_key_overrides
.as_ref()
.and_then(|h| h.get(&feature_flag.key))
{
Ok(hash_key_override.clone())
} else if let Some(request_override) = request_hash_key_override {
// Use the request's anon_distinct_id as fallback when no DB override exists
Ok(request_override.clone())
} else {
Ok(self.distinct_id.clone())
}
} else {
Ok(self.distinct_id.clone())
}
}
}
/// This function takes a identifier and a feature flag key and returns a float between 0 and 1.
/// Given the same identifier and key, it'll always return the same float. These floats are
/// uniformly distributed between 0 and 1, so if we want to show this feature to 20% of traffic
/// we can do _hash(key, identifier) < 0.2
fn get_hash(
&self,
feature_flag: &FeatureFlag,
salt: &str,
aggregation_group_type_index: Option<i32>,
hash_key_overrides: Option<&HashMap<String, String>>,
request_hash_key_override: &Option<String>,
) -> Result<f64, FlagError> {
let hashed_identifier = self.hashed_identifier(
feature_flag,
aggregation_group_type_index,
hash_key_overrides,
request_hash_key_override,
)?;
if hashed_identifier.is_empty() {
// Nothing to hash. `check_rollout` compares `hash <= percentage / 100.0`, so a
// 0.0 hash matches every rollout threshold, including 0.
return Ok(0.0);
}
calculate_hash(&format!("{}.", feature_flag.key), &hashed_identifier, salt)
}
fn get_holdout_hash(
&self,
feature_flag: &FeatureFlag,
salt: Option<&str>,
request_hash_key_override: &Option<String>,
) -> Result<f64, FlagError> {
// Holdouts use the flag-level aggregation for hashing
let hashed_identifier = self.hashed_identifier(
feature_flag,
feature_flag.get_group_type_index(),
None,
request_hash_key_override,
)?;
let hash = calculate_hash("holdout-", &hashed_identifier, salt.unwrap_or(""))?;
Ok(hash)
}
/// Check if a feature flag should be shown based on its rollout percentage.
///
/// Calculates a hash of the identifier (determined by `aggregation_group_type_index`)
/// and compares it to the rollout percentage. Returns whether the flag matched and why.
fn check_rollout(
&self,
feature_flag: &FeatureFlag,
rollout_percentage: f64,
aggregation_group_type_index: Option<i32>,
hash_key_overrides: Option<&HashMap<String, String>>,
request_hash_key_override: &Option<String>,
) -> Result<(bool, FeatureFlagMatchReason), FlagError> {
let included = crate::flags::v1_bucketing::is_in_rollout(rollout_percentage, || {
self.get_hash(
feature_flag,
"",
aggregation_group_type_index,
hash_key_overrides,
request_hash_key_override,
)
})?;
if included {
Ok((true, FeatureFlagMatchReason::ConditionMatch))
} else {
Ok((false, FeatureFlagMatchReason::OutOfRolloutBound))
}
}
fn condition_variant(
&self,
flag: &FeatureFlag,
condition: &FlagPropertyGroup,
aggregation: Option<i32>,
hash_key_overrides: Option<&HashMap<String, String>>,
request_hash_key_override: &Option<String>,
) -> Result<Option<String>, FlagError> {
match flag.pinned_variant(condition) {
Some(pinned) => Ok(Some(pinned.to_string())),
None => self.get_matching_variant(
flag,
aggregation,
hash_key_overrides,
request_hash_key_override,
),
}
}
/// Returns the variant key for this flag based on the hashed identifier.
/// The aggregation determines which identifier is hashed (group key vs distinct_id).
pub(crate) fn get_matching_variant(
&self,
feature_flag: &FeatureFlag,
aggregation_group_type_index: Option<i32>,
hash_key_overrides: Option<&HashMap<String, String>>,
request_hash_key_override: &Option<String>,
) -> Result<Option<String>, FlagError> {
let hash = self.get_hash(
feature_flag,
"variant",
aggregation_group_type_index,
hash_key_overrides,
request_hash_key_override,
)?;
Ok(
crate::flags::v1_bucketing::select_variant(hash, feature_flag.get_variants())
.map(str::to_owned),
)
}
/// Get matching payload for a feature flag.
///
/// This function retrieves the payload associated with a matching variant of a feature flag.
/// It takes the matched variant key and the feature flag itself as inputs and returns the payload.
fn get_matching_payload(
&self,
match_variant: Option<&str>,
feature_flag: &FeatureFlag,
) -> Option<serde_json::Value> {
let variant = match_variant.unwrap_or("true");
feature_flag.get_payload(variant)
}
/// Prepares all database-sourced data needed for flag evaluation.
/// This includes:
/// - Static cohort memberships
/// - Realtime cohort memberships (via behavioral cohorts database)
/// - Group type mappings
/// - Person and group properties
///
/// The data is cached in FlagEvaluationState to avoid repeated DB lookups
/// during subsequent flag evaluations.
pub async fn prepare_flag_evaluation_state(
&mut self,
flags: &[&FeatureFlag],
) -> Result<(), FlagError> {
// Use preloaded cohorts from the flags cache when available (already scoped
// to only referenced cohorts). Fall back to CohortCacheManager which fetches
// ALL cohorts for the team.
let cohorts: Arc<[Cohort]> = match self.preloaded_cohorts.take() {
Some(preloaded) => {
inc(
FLAG_COHORT_SOURCE_COUNTER,
&[("source".to_string(), "preloaded".to_string())],
1,
);
preloaded
}
None => {
inc(
FLAG_COHORT_SOURCE_COUNTER,
&[("source".to_string(), "cache_manager".to_string())],
1,
);
Arc::from(self.cohort_cache.get_cohorts(self.team_id).await?)
}
};
self.flag_evaluation_state.set_cohorts(Arc::clone(&cohorts));
// Get static cohort IDs
// NOTE: relies on `is_static` and `uses_realtime_membership()` being mutually exclusive
// (a cohort with is_static=true should never have CohortType::Realtime/Behavioral).
debug_assert!(
!cohorts
.iter()
.any(|c| c.is_static && self.membership_stamp_policy.uses_realtime_membership(c)),
"Cohort cannot be both static and realtime"
);
let static_cohort_ids: Vec<CohortId> = cohorts
.iter()
.filter(|c| c.is_static)
.map(|c| c.id)
.collect();
// Load group type mappings if needed. Errors are intentionally not propagated here:
// in the batch path (evaluate_flags_with_overrides), a group type mapping failure
// should not poison person-based flags in the same batch. prepare_group_data
// gracefully returns an empty map when the mapping was never loaded, so
// group-based flags will fail individually rather than taking down the whole batch.
if self.initialize_group_type_mappings_if_needed(flags).await {
tracing::warn!("Failed to init group type mappings");
}
// Then prepare group mappings and properties
// This should be _wicked_ fast since it's async and is just pulling from a cache that's already in memory
let group_timer = common_metrics::timing_guard(FLAG_GROUP_CACHE_FETCH_TIME, &[]);
let group_data = self.prepare_group_data(flags)?;
group_timer.fin();
// Single DB operation for properties and cohorts
let db_fetch_timer = common_metrics::timing_guard(FLAG_DB_PROPERTIES_FETCH_TIME, &[]);
match before_persons_db_deadline(
self.persons_db_deadline,
db_operations::FETCH_PROPERTIES,
fetch_and_locally_cache_all_relevant_properties(
&mut self.flag_evaluation_state,
self.router.get_persons_reader().clone(),
self.distinct_id.clone(),
self.team_id,
&group_data,
static_cohort_ids,
),
)
.await
{
Ok(_) => {
inc(DB_PERSON_AND_GROUP_PROPERTIES_READS_COUNTER, &[], 1);
db_fetch_timer.label("outcome", "success").fin();
}
Err(e) => {
error!(
"Error fetching properties for team {} distinct_id {}: {:?}",
self.team_id, self.distinct_id, e
);
db_fetch_timer.label("outcome", "error").fin();
return Err(e);
}
}
// Fetch realtime cohort memberships for Realtime/Behavioral cohorts.
// This is a separate DB call to the behavioral cohorts database, isolated from
// the static cohort path above which uses the persons_reader pool.
let realtime_cohort_ids: Vec<CohortId> = if self.enable_realtime_cohort_evaluation {
cohorts
.iter()
.inspect(|c| record_stamp_policy_divergence(c, self.membership_stamp_policy))
.filter(|c| self.membership_stamp_policy.uses_realtime_membership(c))
.map(|c| c.id)
.collect()
} else {
Vec::new()
};
if !realtime_cohort_ids.is_empty() {
with_canonical_log(|log| {
log.realtime_cohorts_evaluated += realtime_cohort_ids.len();
});
let all_non_member = || -> HashMap<CohortId, bool> {
realtime_cohort_ids.iter().map(|id| (*id, false)).collect()
};
let realtime_memberships = if let Some(person_uuid) =
self.flag_evaluation_state.get_person_uuid()
{
let query_labels = [("team_id".to_string(), self.team_id.to_string())];
// High precision: cache hits complete in microseconds, and plain
// timing_guard truncates to integer ms, collapsing them all to 0.
let realtime_timer =
timing_guard_high_precision(FLAG_REALTIME_COHORT_QUERY_TIME, &query_labels);
let realtime_start = std::time::Instant::now();
let result = self
.cohort_membership_provider
.check_memberships(self.team_id, person_uuid, &realtime_cohort_ids)
.await;
let duration = realtime_start.elapsed();
realtime_timer.fin();
with_canonical_log(|log| {
log.realtime_cohort_queries += 1;
log.realtime_cohort_query_time_ms += duration.as_millis() as u64;
});
match result {
Ok(memberships) => memberships,
Err(e) => {
inc(FLAG_REALTIME_COHORT_QUERY_ERROR_COUNTER, &query_labels, 1);
warn!(
team_id = self.team_id,
person_uuid = %person_uuid,
realtime_cohort_count = realtime_cohort_ids.len(),
error = %e,
"Realtime cohort membership lookup failed, treating all as non-members"
);
// Graceful degradation: treat all realtime cohorts as non-members
all_non_member()
}
}
} else {
// No person UUID available (anonymous user). Realtime cohorts return false.
all_non_member()
};
self.flag_evaluation_state
.merge_cohort_matches(realtime_memberships);
}
Ok(())
}
/// Every group type index a flag can read during evaluation: flag-level aggregation,
/// per-condition aggregation, and the explicit `group_type_index` on individual group
/// property filters. Indexes may repeat, so collect into a set where uniqueness matters.
///
/// The filter-level indexes matter for mixed targeting, where a person-aggregated
/// condition still carries a group filter with its own index.
/// `PropertyContext::resolve_for_filter` resolves such a filter against exactly that
/// index, so omitting it from the fetch would silently resolve the filter against an
/// empty map instead of the group's real properties.
pub(crate) fn referenced_group_type_indexes(
flag: &FeatureFlag,
) -> impl Iterator<Item = GroupTypeIndex> + '_ {
let requirements = flag.filters.requirements();
requirements
.aggregation_group_type_indexes
.into_iter()
.chain(requirements.group_property_type_indexes)
}
/// Builds a paired mapping from group type index to group key for flag
/// evaluation, filtered to only the group types required by the given flags.
fn prepare_group_data(
&mut self,
flags: &[&FeatureFlag],
) -> Result<HashMap<GroupTypeIndex, String>, FlagError> {
let required_type_indexes: HashSet<GroupTypeIndex> = flags
.iter()
.flat_map(|flag| Self::referenced_group_type_indexes(flag))
.collect();
if required_type_indexes.is_empty() {
return Ok(HashMap::new());
}
let Some(mapping) = self.group_type_mapping.mapping() else {
return Ok(HashMap::new());
};
let types_to_indexes = mapping.group_types_to_indexes();
let group_type_to_key: HashMap<GroupTypeIndex, String> = self
.groups
.iter()
.filter_map(|(group_type, group_key_value)| {
let group_key = match group_key_value {
Value::String(s) => s.clone(),
Value::Number(n) => n.to_string(),
_ => return None,
};
types_to_indexes
.get(group_type)
.cloned()
.filter(|idx| required_type_indexes.contains(idx))
.map(|group_type_index| (group_type_index, group_key))
})
.collect();
Ok(group_type_to_key)
}
/// Get person properties from the `FlagEvaluationState` only, returning a reference.
fn get_person_properties_from_evaluation_state(
&self,
) -> Result<&HashMap<String, Value>, FlagError> {
match &self.flag_evaluation_state.person_property_state {
PersonPropertyState::Fetched(properties) => {
inc(
PROPERTY_CACHE_HITS_COUNTER,
&[("type".to_string(), "person_properties".to_string())],
1,
);
with_canonical_log(|log| log.eval.property_cache_hits += 1);
Ok(properties)
}
PersonPropertyState::Skipped => {
tracing::debug!(
"Person properties not in cache — DB prep was skipped (overrides cover all needed keys)"
);
Err(FlagError::person_not_found())
}
PersonPropertyState::Pending => {
inc(
PROPERTY_CACHE_MISSES_COUNTER,
&[
("type".to_string(), "person_properties".to_string()),
("reason".to_string(), "db_prep_never_ran".to_string()),
],
1,
);
with_canonical_log(|log| {
log.eval.property_cache_misses += 1;
log.eval.person_properties_not_cached = true;
});
tracing::error!("Person properties not found — DB prep never ran");
Err(FlagError::person_not_found())
}
}
}
/// Get group properties for the given group type index from the `FlagEvaluationState` only. Returns empty HashMap if not found.
fn get_group_properties_from_evaluation_state(
&self,
group_type_index: GroupTypeIndex,
) -> Result<HashMap<String, Value>, FlagError> {
let group_properties = self.flag_evaluation_state.get_group_properties();
if let Some(properties) = group_properties.get(&group_type_index) {
inc(
PROPERTY_CACHE_HITS_COUNTER,
&[("type".to_string(), "group_properties".to_string())],
1,
);
with_canonical_log(|log| log.eval.property_cache_hits += 1);
let mut result = HashMap::new();
result.clone_from(properties);
Ok(result)
} else {
inc(
PROPERTY_CACHE_MISSES_COUNTER,
&[("type".to_string(), "group_properties".to_string())],
1,
);
with_canonical_log(|log| {
log.eval.property_cache_misses += 1;
log.eval.group_properties_not_cached = true;
});
// Return an empty HashMap instead of an error: a group with no `posthog_group`
// row genuinely has no properties. Whether the fetch actually ran is tracked
// separately by `FlagEvaluationState::group_properties_pending`, which
// `is_condition_match` consults so a fetch miss can't be read as "unset".
Ok(HashMap::new())
}
}
/// If experience continuity is enabled, we need to process the hash key override.
/// See [`FeatureFlagMatcher::process_hash_key_override`] for more details.
async fn process_hash_key_override_if_needed(
&self,
flags_have_experience_continuity_enabled: bool,
hash_key_override: Option<String>,
) -> (Option<HashMap<String, String>>, bool) {
let hash_key_timer = common_metrics::timing_guard(FLAG_HASH_KEY_PROCESSING_TIME, &[]);
let (hash_key_overrides, flag_hash_key_override_error) =
if flags_have_experience_continuity_enabled {
common_metrics::inc(FLAG_EXPERIENCE_CONTINUITY_REQUESTS_COUNTER, &[], 1);
with_canonical_log(|log| log.outcome_marks.mark_needs_persons());
match hash_key_override {
Some(hash_key) => {
let target_distinct_ids = vec![self.distinct_id.clone(), hash_key.clone()];
self.process_hash_key_override(hash_key, target_distinct_ids)
.await
}
// If no hash key override is provided, we need to look up existing overrides.
// Most of the time this is fine because our client side sdks usually include $anon_distinct_id in their requests,
// but if a customer is using hash key overrides across a client sdk and a server sdk then the experience
// will be inconsistent because server sdks won't include $anon_distinct_id in their requests.
// In addition, this behavior is consistent with /decide.
None => {
match before_persons_db_deadline(
self.persons_db_deadline,
db_operations::GET_HASH_KEY_OVERRIDES,
get_feature_flag_hash_key_overrides(
self.router.get_persons_reader().clone(),
pool_names::PERSONS_READER,
self.router.get_persons_writer().clone(),
self.team_id,
vec![self.distinct_id.clone()],
),
)
.await
{
Ok(overrides) => (Some(overrides), false),
Err(e) => {
error!(
"Failed to get feature flag hash key overrides for team {} distinct_id {}: {:?}",
self.team_id, self.distinct_id, e
);
(None, true)
}
}
}
}
} else {
// if experience continuity is not enabled, we don't need to worry about hash key overrides
(None, false)
};
// If there was an error in processing hash key overrides, increment the error counter
if flag_hash_key_override_error {
let reason = "hash_key_override_error";
common_metrics::inc(
FLAG_EVALUATION_ERROR_COUNTER,
&[("reason".to_string(), reason.to_string())],
1,
);
}
hash_key_timer
.label(
"outcome",
if flag_hash_key_override_error {
"error"
} else {
"success"
},
)
.fin();
// Track hash key override status in canonical log
if flag_hash_key_override_error {
with_canonical_log(|log| log.hash_key_override_status = Some("error"));
} else if let Some(ref overrides) = hash_key_overrides {
let status = if overrides.is_empty() {
"empty"
} else {
"found"
};
with_canonical_log(|log| log.hash_key_override_status = Some(status));
}
(hash_key_overrides, flag_hash_key_override_error)
}
/// Initializes the group type mapping cache if needed.
///
/// This function checks if any of the feature flags have group type indices and initializes the group type mapping cache if needed.
/// It returns a boolean indicating if there were any errors while initializing the group type mapping cache.
async fn initialize_group_type_mappings_if_needed(&mut self, flags: &[&FeatureFlag]) -> bool {
// The lookup is request-scoped, and the batch path runs it before
// `prepare_flag_evaluation_state` runs it again. `GroupTypeCacheManager` does not cache
// failures, so without reusing the recorded outcome a single outage costs every affected
// request two waits on two failed queries.
match self.group_type_mapping {
GroupTypeMappingState::Loaded(_) => return false,
GroupTypeMappingState::Failed(_) => return true,
GroupTypeMappingState::Uninitialized => {}
}
// Check if we need to fetch group type mappings — any flag references a group type,
// whether through aggregation or through an individual group property filter. The
// filter case must be included: without the mapping, `prepare_group_data` returns
// an empty map and those filters evaluate against no properties at all.
let has_type_indexes = flags.iter().any(|flag| {
!self.filtered_out_flag_ids.contains(&flag.id)
&& Self::referenced_group_type_indexes(flag).next().is_some()
});
if !has_type_indexes {
return false;
}
with_canonical_log(|log| log.outcome_marks.mark_needs_persons());
let group_type_mapping_timer = common_metrics::timing_guard(FLAG_GROUP_DB_FETCH_TIME, &[]);
let mut errors_while_computing_flags = false;
// The cache applies the deadline itself, so that this request's deadline cannot cancel
// the fetch that other requests for the team wait on.
let mappings = self
.group_type_cache
.get_mappings(self.team_id, self.persons_db_deadline)
.await;
record_persons_db_deadline_exceeded(db_operations::FETCH_GROUP_TYPE_MAPPING, &mappings);
match mappings {
Ok(mapping) => {
if mapping.is_empty() {
// Empty mappings are not an error — the team simply has no group types
// configured. Group-based flags won't match, but person flags in the same
// batch should succeed without surfacing errorsWhileComputingFlags to the
// client.
tracing::warn!("No group type mappings found for team {}", self.team_id);
}
self.group_type_mapping = GroupTypeMappingState::Loaded(mapping);
}
Err(e) => {
errors_while_computing_flags = true;
self.group_type_mapping = GroupTypeMappingState::Failed(Arc::new(e));
}
}
group_type_mapping_timer
.label(
"outcome",
if errors_while_computing_flags {
"error"
} else {
"success"
},
)
.fin();
errors_while_computing_flags
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn test_promote_evaluation_type_none_to_sequential() {
assert_eq!(
EvaluationType::promote(None, EvaluationType::Sequential),
Some(EvaluationType::Sequential)
);
}
#[test]
fn test_promote_evaluation_type_none_to_parallel() {
assert_eq!(
EvaluationType::promote(None, EvaluationType::Parallel),
Some(EvaluationType::Parallel)
);
}
#[test]
fn test_promote_evaluation_type_sequential_to_parallel() {
assert_eq!(
EvaluationType::promote(Some(EvaluationType::Sequential), EvaluationType::Parallel),
Some(EvaluationType::Parallel)
);
}
#[test]
fn test_promote_evaluation_type_parallel_stays_sticky() {
assert_eq!(
EvaluationType::promote(Some(EvaluationType::Parallel), EvaluationType::Sequential),
Some(EvaluationType::Parallel)
);
}
#[test]
fn test_promote_evaluation_type_sequential_stays_sequential() {
assert_eq!(
EvaluationType::promote(Some(EvaluationType::Sequential), EvaluationType::Sequential),
Some(EvaluationType::Sequential)
);
}
#[test]
fn test_panic_fallback_preserves_flag_identity() {
let team_id = 42;
let snapshots = vec![
FlagSnapshot {
key: "flag_a".to_string(),
id: 10,
version: Some(3),
non_v1: None,
},
FlagSnapshot {
key: "flag_b".to_string(),
id: 20,
version: None,
non_v1: Some(Arc::new(NonV1Config {
parsed_v2: None,
document: serde_json::value::RawValue::from_string("{}".to_string()).unwrap(),
})),
},
FlagSnapshot {
key: "flag_c".to_string(),
id: 30,
version: Some(1),
non_v1: None,
},
];
let results = FeatureFlagMatcher::build_panic_fallback(snapshots, team_id);
assert_eq!(results.len(), 3);
let (stub_a, err_a) = &results[0];
assert_eq!(stub_a.key, "flag_a");
assert_eq!(stub_a.id, 10);
assert_eq!(stub_a.version, Some(3));
assert!(matches!(
err_a,
Err(FlagError::InternalError {
code: "batch_evaluation_panicked",
..
})
));
let (stub_b, err_b) = &results[1];
assert_eq!(stub_b.key, "flag_b");
assert_eq!(stub_b.id, 20);
assert_eq!(stub_b.version, None);
assert!(!stub_b.filters.is_v1());
assert!(stub_a.filters.is_v1());
assert!(matches!(
err_b,
Err(FlagError::InternalError {
code: "batch_evaluation_panicked",
..
})
));
let (stub_c, err_c) = &results[2];
assert_eq!(stub_c.key, "flag_c");
assert_eq!(stub_c.id, 30);
assert_eq!(stub_c.version, Some(1));
assert!(matches!(
err_c,
Err(FlagError::InternalError {
code: "batch_evaluation_panicked",
..
})
));
for (stub, _) in &results {
assert_eq!(stub.team_id, team_id);
assert!(stub.active);
assert_eq!(stub.name, None);
assert!(!stub.deleted);
assert!(stub.filters.groups.is_empty());
}
}
/// A stored hash-key override must only steer bucketing while the flag *currently*
/// has experience continuity enabled. When continuity is turned off, the row written
/// back while it was on is never deleted — so the matcher must fall back to the raw
/// distinct_id and ignore the stale override, otherwise every distinct_id of the
/// person keeps bucketing on the old key and resolves to the same stale value.
#[rstest::rstest]
#[case::continuity_off_ignores_stale_override(Some(false), None, "logged-in-username")]
#[case::continuity_unset_ignores_stale_override(None, None, "logged-in-username")]
#[case::continuity_on_applies_override(Some(true), None, "stale-anon-id")]
#[case::continuity_on_stored_override_beats_request_override(
Some(true),
Some("request-anon-id"),
"stale-anon-id"
)]
#[tokio::test]
async fn test_hashed_identifier_respects_current_continuity_for_stored_override(
#[case] ensure_experience_continuity: Option<bool>,
#[case] request_hash_key_override: Option<&str>,
#[case] expected_identifier: &str,
) {
use crate::utils::test_utils::{mock_group_type_cache, TestContext};
let context = TestContext::new(None).await;
let cohort_cache = Arc::new(CohortCacheManager::new(
context.non_persons_reader.clone(),
None,
None,
));
let matcher = FeatureFlagMatcher::new(
"logged-in-username".to_string(),
None, // device_id
1,
context.create_postgres_router(),
cohort_cache,
mock_group_type_cache(HashMap::new()),
None,
);
// Override left behind from when this flag still had continuity enabled.
let overrides = HashMap::from([("my_flag".to_string(), "stale-anon-id".to_string())]);
let flag = FeatureFlag {
key: "my_flag".to_string(),
ensure_experience_continuity,
..Default::default()
};
let request_override = request_hash_key_override.map(str::to_string);
let identifier = matcher
.hashed_identifier(&flag, None, Some(&overrides), &request_override)
.unwrap();
assert_eq!(identifier, expected_identifier);
}
#[rstest::rstest]
#[case::injects_when_overrides_absent("user_42", None, "user_42", vec![])]
#[case::injects_when_overrides_lack_distinct_id(
"user_42",
Some(vec![("email", "[email protected]")]),
"user_42",
vec![("email", "[email protected]")],
)]
#[case::explicit_override_wins(
"user_42",
Some(vec![("distinct_id", "explicit")]),
"explicit",
vec![],
)]
#[case::injects_empty_string_when_overrides_absent("", None, "", vec![])]
#[case::injects_empty_string_when_overrides_lack_distinct_id(
"",
Some(vec![("foo", "bar")]),
"",
vec![("foo", "bar")],
)]
#[case::explicit_override_wins_over_empty_request_distinct_id(
"",
Some(vec![("distinct_id", "explicit")]),
"explicit",
vec![],
)]
fn test_merge_distinct_id_into_person_properties(
#[case] request_distinct_id: &str,
#[case] overrides: Option<Vec<(&str, &str)>>,
#[case] expected_distinct_id: &str,
#[case] expected_extras: Vec<(&str, &str)>,
) {
let overrides = overrides.map(|kvs| {
kvs.into_iter()
.map(|(k, v)| (k.to_string(), Value::String(v.to_string())))
.collect::<HashMap<_, _>>()
});
let result = merge_distinct_id_into_person_properties(request_distinct_id, overrides);
assert_eq!(
result.get("distinct_id"),
Some(&Value::String(expected_distinct_id.to_string())),
);
for (k, v) in &expected_extras {
assert_eq!(result.get(*k), Some(&Value::String((*v).to_string())));
}
assert_eq!(result.len(), 1 + expected_extras.len());
}
#[test]
fn test_cohort_analysis_keeps_resolved_memberships_when_another_cohort_fails() {
// A flag can name a cohort the flags payload no longer carries, because Django omits
// deleted and cross-team cohorts but keeps the filters that name them. Resolving the set as
// a unit drops the memberships that did resolve along with it.
let cohort: Cohort = serde_json::from_value(serde_json::json!({
"id": 1,
"team_id": 1,
"deleted": false,
"is_calculating": false,
"is_static": false,
"errors_calculating": 0,
"groups": [],
"filters": {
"properties": {
"type": "OR",
"values": [{
"type": "OR",
"values": [{
"key": "plan",
"type": "person",
"value": "enterprise",
"operator": "exact"
}]
}]
}
}
}))
.unwrap();
// Cohort 999 comes first, so a resolver that stopped on the first failure would lose
// cohort 1 instead of reporting it.
let filters: Vec<PropertyFilter> = [999, 1]
.into_iter()
.map(|id| {
serde_json::from_value(serde_json::json!({
"key": "id",
"value": id,
"type": "cohort",
"operator": "in"
}))
.unwrap()
})
.collect();
let filter_refs: Vec<&PropertyFilter> = filters.iter().collect();
let target_properties =
HashMap::from([("plan".to_string(), Value::String("enterprise".to_string()))]);
// Cohort 999 is absent from the loaded list, so resolving it fails.
let (resolved, errors) = FeatureFlagMatcher::resolve_cohort_matches_from_cache(
&filter_refs,
&target_properties,
&[cohort],
HashMap::new(),
PropertyMatchingContext::new(Tz::UTC, false),
);
assert_eq!(
errors.len(),
1,
"the failing cohort must be reported, so the strict path can still fail on it"
);
assert_eq!(
resolved.get(&1),
Some(&true),
"a resolved membership must survive another cohort failing"
);
assert_eq!(
resolved.get(&999),
None,
"an unresolvable cohort must be absent, so analysis reads it as unknown"
);
}
}