: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 std::collections::hash_map::Entry;
use std::collections::HashMap;
use std::fmt;
use chrono::{DateTime, Utc};
use chrono_tz::Tz;
use serde_json::Value;
use uuid::Uuid;
use super::config_v2::{Config, Outcome, RolloutMiss, Rule, Variant};
use super::flag_matching_utils::calculate_hash;
use super::flag_request::MAX_DISTINCT_ID_LEN;
use super::v1_bucketing::is_in_rollout;
use crate::api::errors::FlagError;
use crate::handler::canonical_log::truncate_chars;
use crate::properties::property_matching::{
match_property_input, FlagMatchingError, PropertyMatchInput, PropertyMatchingContext,
};
use crate::properties::property_models::CompiledRegex;
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum RuleKind {
TargetedRelease,
PercentageRollout,
Experiment,
}
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
pub enum HashUse {
Rollout,
Variant,
Holdout,
}
impl HashUse {
pub fn hash(self, seed: &str, subject: &str) -> Result<f64, EvaluationError> {
match self {
Self::Rollout => calculate_hash(&format!("{seed}."), subject, ""),
Self::Variant => calculate_hash(&format!("{seed}."), subject, "variant"),
// No ".": a holdout seed of "holdout-" reproduces v1's `get_holdout_hash`.
Self::Holdout => calculate_hash(seed, subject, ""),
}
.map_err(|_| EvaluationError::Hash)
}
}
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub struct MatchedRule {
pub id: Uuid,
pub index: usize,
pub kind: RuleKind,
}
/// `value` borrows the parsed JSON of the flag's return type from the configuration; `None`
/// is a null default.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum Evaluation<'a> {
TargetingMatch {
value: &'a Value,
rule: MatchedRule,
},
ExperimentSplit {
value: &'a Value,
rule: MatchedRule,
variant_key: &'a str,
},
RolloutMiss {
value: Option<&'a Value>,
rule: MatchedRule,
},
ExperimentPaused {
value: Option<&'a Value>,
rule: MatchedRule,
},
Holdout {
value: Option<&'a Value>,
rule: MatchedRule,
},
NoRuleMatch {
value: Option<&'a Value>,
},
}
impl RuleKind {
pub const fn as_str(self) -> &'static str {
match self {
Self::TargetedRelease => "targeted_release",
Self::PercentageRollout => "percentage_rollout",
Self::Experiment => "experiment",
}
}
}
impl<'a> Evaluation<'a> {
pub const fn code(self) -> &'static str {
match self {
Self::TargetingMatch { .. } => "targeting_match",
Self::ExperimentSplit { .. } => "experiment_split",
Self::RolloutMiss { .. } => "rollout_miss",
Self::ExperimentPaused { .. } => "experiment_paused",
Self::Holdout { .. } => "holdout",
Self::NoRuleMatch { .. } => "no_rule_match",
}
}
pub fn value(self) -> Option<&'a Value> {
match self {
Self::TargetingMatch { value, .. } | Self::ExperimentSplit { value, .. } => Some(value),
Self::RolloutMiss { value, .. }
| Self::ExperimentPaused { value, .. }
| Self::Holdout { value, .. }
| Self::NoRuleMatch { value } => value,
}
}
pub fn rule(self) -> Option<MatchedRule> {
match self {
Self::TargetingMatch { rule, .. }
| Self::ExperimentSplit { rule, .. }
| Self::RolloutMiss { rule, .. }
| Self::ExperimentPaused { rule, .. }
| Self::Holdout { rule, .. } => Some(rule),
Self::NoRuleMatch { .. } => None,
}
}
pub fn variant_key(self) -> Option<&'a str> {
match self {
Self::ExperimentSplit { variant_key, .. } => Some(variant_key),
_ => None,
}
}
pub fn description(self) -> String {
match self {
Self::TargetingMatch { rule, .. } => format!("Matched rule {}", rule.index + 1),
Self::ExperimentSplit { rule, .. } => {
format!("Rule {} experiment split", rule.index + 1)
}
Self::RolloutMiss { rule, .. } => format!("Rule {} rollout miss", rule.index + 1),
Self::ExperimentPaused { rule, .. } => format!("Rule {} is paused", rule.index + 1),
Self::Holdout { rule, .. } => format!("Rule {} holdout", rule.index + 1),
Self::NoRuleMatch { .. } => "No rule matched".to_string(),
}
}
}
/// The parts of an [`Evaluation`] the v4 record reads, owned so they outlive the configuration.
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct EvaluationDetail {
pub code: &'static str,
/// `Value::Null` is a null default.
pub value: Value,
pub rule: Option<MatchedRule>,
pub variant_key: Option<String>,
pub description: String,
}
impl From<Evaluation<'_>> for EvaluationDetail {
fn from(evaluation: Evaluation<'_>) -> Self {
Self {
code: evaluation.code(),
value: evaluation.value().cloned().unwrap_or(Value::Null),
rule: evaluation.rule(),
variant_key: evaluation.variant_key().map(str::to_owned),
description: evaluation.description(),
}
}
}
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum EvaluationError {
MissingContext,
InvalidProperty,
InvalidRegex,
Hash,
}
impl From<EvaluationError> for FlagError {
fn from(error: EvaluationError) -> Self {
FlagError::flag_evaluation(error)
}
}
#[derive(Clone, Copy)]
pub enum PersonProperties<'a> {
Complete(&'a HashMap<String, Value>),
Partial(&'a HashMap<String, Value>),
Unavailable,
}
pub struct EvaluationContext<'a> {
// The service adapter supplies the person distinct ID, without device or continuity overrides.
pub person_identifier: &'a str,
pub properties: PersonProperties<'a>,
pub timezone: Tz,
pub use_explicit_exact_matching: bool,
pub now: DateTime<Utc>,
}
impl fmt::Debug for EvaluationContext<'_> {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
f.debug_struct("EvaluationContext").finish_non_exhaustive()
}
}
/// Borrows the reader's validated configuration. Admission and eligibility belong to the caller.
/// Cheap to build per request; compiled patterns live on the cached configuration.
pub struct Evaluator<'a> {
config: &'a Config,
}
impl fmt::Debug for Evaluator<'_> {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
f.debug_struct("V2Evaluator")
.field("rule_count", &self.config.rules.len())
.finish_non_exhaustive()
}
}
impl<'a> Evaluator<'a> {
pub fn new(config: &'a Config) -> Self {
Self { config }
}
pub fn evaluate(
&self,
context: &EvaluationContext<'_>,
) -> Result<Evaluation<'a>, EvaluationError> {
self.evaluate_with_hash(context, HashUse::hash)
}
/// Test seam for injecting hash values; not part of the supported API.
#[doc(hidden)]
pub fn evaluate_with_hash(
&self,
context: &EvaluationContext<'_>,
hash: impl FnMut(HashUse, &str, &str) -> Result<f64, EvaluationError>,
) -> Result<Evaluation<'a>, EvaluationError> {
let subject = truncate_chars(context.person_identifier, MAX_DISTINCT_ID_LEN);
let matching =
PropertyMatchingContext::new(context.timezone, context.use_explicit_exact_matching)
.at_time(context.now);
// Unavailable properties fail only once a predicate is reached.
let person_properties = match context.properties {
PersonProperties::Complete(properties) => Some((properties, false)),
PersonProperties::Partial(properties) => Some((properties, true)),
PersonProperties::Unavailable => None,
};
let mut draws = Draws {
subject,
hash,
cache: HashMap::new(),
};
let default = self.config.default_value.as_ref();
for (index, rule) in self.config.rules.iter().enumerate() {
if !rule_targets(rule, person_properties, matching)? {
continue;
}
let matched_rule = |kind| MatchedRule {
id: rule.id,
index,
kind,
};
let (rule, on_rollout_miss) = match &rule.outcome {
Outcome::TargetedRelease { value } => {
return Ok(Evaluation::TargetingMatch {
value,
rule: matched_rule(RuleKind::TargetedRelease),
})
}
Outcome::PercentageRollout {
value,
rollout_percentage,
on_rollout_miss,
seed,
} => {
let rule = matched_rule(RuleKind::PercentageRollout);
if draws.includes(HashUse::Rollout, seed, *rollout_percentage)? {
return Ok(Evaluation::TargetingMatch { value, rule });
}
(rule, on_rollout_miss)
}
Outcome::Experiment {
paused,
rollout_percentage,
on_rollout_miss,
seed,
variants,
holdout,
} => {
let rule = matched_rule(RuleKind::Experiment);
if *paused {
return Ok(Evaluation::ExperimentPaused {
value: default,
rule,
});
}
if let Some(holdout) = holdout {
if draws.includes(
HashUse::Holdout,
&holdout.seed,
holdout.exclusion_percentage,
)? {
return Ok(Evaluation::Holdout {
value: default,
rule,
});
}
}
if draws.includes(HashUse::Rollout, seed, *rollout_percentage)? {
let variant = select_variant(draws.draw(HashUse::Variant, seed)?, variants);
return Ok(Evaluation::ExperimentSplit {
value: &variant.value,
rule,
variant_key: &variant.key,
});
}
(rule, on_rollout_miss)
}
};
if *on_rollout_miss == RolloutMiss::ReturnDefault {
return Ok(Evaluation::RolloutMiss {
value: default,
rule,
});
}
}
Ok(Evaluation::NoRuleMatch { value: default })
}
}
/// The hashes one evaluation draws for its subject; repeated draws with the same use and seed
/// share a hash.
struct Draws<'a, 's, H> {
subject: &'s str,
hash: H,
cache: HashMap<(HashUse, &'a str), f64>,
}
impl<'a, H: FnMut(HashUse, &str, &str) -> Result<f64, EvaluationError>> Draws<'a, '_, H> {
fn draw(&mut self, hash_use: HashUse, seed: &'a str) -> Result<f64, EvaluationError> {
match self.cache.entry((hash_use, seed)) {
Entry::Occupied(entry) => Ok(*entry.get()),
Entry::Vacant(entry) => {
(self.hash)(hash_use, seed, self.subject).map(|value| *entry.insert(value))
}
}
}
/// An empty subject never enters a rollout or a holdout, so it is never hashed.
fn includes(
&mut self,
hash_use: HashUse,
seed: &'a str,
percentage: f64,
) -> Result<bool, EvaluationError> {
Ok(!self.subject.is_empty() && is_in_rollout(percentage, || self.draw(hash_use, seed))?)
}
}
/// Boundaries add left to right in binary64; past the last one (rounding, or a hash of 1.0)
/// the last variant wins. The parser admits at least two variants.
fn select_variant(hash: f64, variants: &[Variant]) -> &Variant {
let mut boundary = 0.0;
for variant in variants {
boundary += variant.weight / 100.0;
if hash < boundary {
return variant;
}
}
&variants[variants.len() - 1]
}
/// Whether every predicate of `rule` matches; a reached error fails the evaluation.
fn rule_targets(
rule: &Rule,
person_properties: Option<(&HashMap<String, Value>, bool)>,
matching: PropertyMatchingContext,
) -> Result<bool, EvaluationError> {
for predicate in &rule.targeting {
let (properties, partial) = person_properties.ok_or(EvaluationError::MissingContext)?;
if partial && !properties.contains_key(&predicate.key) {
return Err(EvaluationError::MissingContext);
}
let regex = predicate.compiled_regex.as_ref();
// An invalid pattern is not a conclusive false result that negation can invert.
if matches!(regex, Some(CompiledRegex::InvalidPattern)) {
return Err(EvaluationError::InvalidRegex);
}
let matched = match_property_input(
PropertyMatchInput {
key: &predicate.key,
value: predicate.value.as_ref(),
operator: predicate.operator,
compiled_regex: regex,
},
properties,
partial,
matching,
)
.map_err(|error| match error {
FlagMatchingError::MissingProperty(_)
| FlagMatchingError::InconclusiveOperatorMatch => EvaluationError::MissingContext,
FlagMatchingError::ValidationError(_) => EvaluationError::InvalidProperty,
FlagMatchingError::InvalidRegexPattern => EvaluationError::InvalidRegex,
})?;
if matched == predicate.negation {
return Ok(false);
}
}
Ok(true)
}