Skip to content

: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.

16.2 KB
Raw Blame
use std::collections::HashSet;
use std::fmt;

use once_cell::sync::Lazy;
use serde_json::value::RawValue;
use serde_json::{Map, Value};
use uuid::Uuid;

use crate::flags::flag_group_type_mapping::GroupTypeIndex;
use crate::utils::json_size::estimate_json_heap_size;

mod properties;
mod raw;
pub use properties::{Predicate, Subject};
pub(crate) use raw::validate_raw_document;

pub static MAX_CONFIG_BYTES: Lazy<usize> = Lazy::new(|| {
    std::env::var("MAX_FEATURE_FLAG_FILTER_SIZE_BYTES")
        .map(|value| {
            value
                .parse()
                .expect("MAX_FEATURE_FLAG_FILTER_SIZE_BYTES must be a nonnegative integer")
        })
        .unwrap_or(512 * 1024)
});
pub const MAX_RULES: usize = 100;
pub const MAX_PREDICATES: usize = 100;
pub const MAX_SEED_LENGTH: usize = 400;
pub const MAX_SAFE_INTEGER: f64 = 9_007_199_254_740_991.0;
pub const MAX_OBJECT_DEPTH: usize = 20;
pub const CONFIG_FIELDS: &[&str] = &[
    "version",
    "return_type",
    "default_value",
    "rules",
    "aggregation_group_type_index",
];
pub const TARGETED_RELEASE_FIELDS: &[&str] = &[
    "id",
    "rule_type",
    "targeting",
    "description",
    "metadata",
    "value",
];
pub const PERCENTAGE_ROLLOUT_FIELDS: &[&str] = &[
    "id",
    "rule_type",
    "targeting",
    "description",
    "metadata",
    "value",
    "rollout_percentage",
    "on_rollout_miss",
    "assignment_algorithm",
    "seed",
    "assign_by",
];
pub const EXPERIMENT_FIELDS: &[&str] = &[
    "id",
    "rule_type",
    "targeting",
    "description",
    "metadata",
    "paused",
    "rollout_percentage",
    "on_rollout_miss",
    "assignment_algorithm",
    "seed",
    "assign_by",
    "variants",
    "holdout",
];
pub const VARIANT_FIELDS: &[&str] = &["key", "weight", "value"];
pub const HOLDOUT_FIELDS: &[&str] = &["seed", "exclusion_percentage"];
pub const MIN_VARIANTS: usize = 2;
pub const MAX_VARIANTS: usize = 20;
pub const TARGETING_FIELDS: &[&str] = &["properties"];
pub const PROPERTY_FIELDS: &[&str] = &[
    "key",
    "type",
    "value",
    "operator",
    "negation",
    "group_type_index",
    "cohort_name",
    "group_key_names",
    "label",
];

#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum ParseError {
    Malformed(&'static str),
    Unsupported(&'static str),
    LimitExceeded(&'static str),
}

#[derive(Clone)]
pub struct NonV1Config {
    pub parsed_v2: Option<Result<Config, ParseError>>,
    pub(crate) document: Box<RawValue>,
}

impl fmt::Debug for NonV1Config {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_struct("NonV1Config")
            .field("parsed_v2", &self.parsed_v2)
            .finish_non_exhaustive()
    }
}

impl NonV1Config {
    pub(crate) fn estimated_heap_bytes(&self) -> usize {
        std::mem::size_of::<Self>()
            + 2 * std::mem::size_of::<usize>()
            + self.document.get().len()
            + self
                .parsed_v2
                .as_ref()
                .and_then(|parsed| parsed.as_ref().ok())
                .map_or(0, Config::estimated_heap_bytes)
    }
}

#[derive(Clone)]
pub struct Config {
    pub default_value: Option<Value>,
    pub rules: Vec<Rule>,
    /// The group type rules assign by, or `None` for persons. The parser does not admit it yet.
    pub aggregation_group_type_index: Option<GroupTypeIndex>,
}

#[derive(Clone)]
pub struct Rule {
    pub id: Uuid,
    pub targeting: Vec<Predicate>,
    pub outcome: Outcome,
}

#[derive(Clone)]
pub enum Outcome {
    TargetedRelease {
        value: Value,
    },
    PercentageRollout {
        value: Value,
        rollout_percentage: f64,
        on_rollout_miss: RolloutMiss,
        seed: String,
    },
    /// A weighted variant split. An Experiment points at its rule; the rule never names it.
    Experiment {
        paused: bool,
        rollout_percentage: f64,
        on_rollout_miss: RolloutMiss,
        seed: String,
        variants: Vec<Variant>,
        holdout: Option<Holdout>,
    },
}

#[derive(Clone)]
pub struct Variant {
    pub key: String,
    pub weight: f64,
    pub value: Value,
}

/// A holdout that belongs to its rule and has no identity of its own.
#[derive(Clone)]
pub struct Holdout {
    pub seed: String,
    pub exclusion_percentage: f64,
}

#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum RolloutMiss {
    Continue,
    ReturnDefault,
}

impl fmt::Debug for Config {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_struct("V2Config")
            .field("rule_count", &self.rules.len())
            .finish_non_exhaustive()
    }
}

impl fmt::Debug for Rule {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_struct("V2Rule")
            .field("predicate_count", &self.targeting.len())
            .field("outcome", &self.outcome)
            .finish_non_exhaustive()
    }
}

impl fmt::Debug for Outcome {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.write_str(match self {
            Self::TargetedRelease { .. } => "TargetedRelease { .. }",
            Self::PercentageRollout { .. } => "PercentageRollout { .. }",
            Self::Experiment { .. } => "Experiment { .. }",
        })
    }
}

impl Config {
    pub(super) fn parse(document: &Map<String, Value>) -> Result<Self, ParseError> {
        closed(document, CONFIG_FIELDS, "filters")?;
        let return_type = match string(document, "return_type")? {
            "boolean" => ReturnType::Boolean,
            "string" => ReturnType::String,
            "number" => ReturnType::Number,
            "object" => ReturnType::Object,
            _ => return Err(ParseError::Malformed("return_type")),
        };
        if let Some(group) = document.get("aggregation_group_type_index") {
            if !group
                .as_f64()
                .is_some_and(|n| n.is_finite() && n.fract() == 0.0)
            {
                return Err(ParseError::Malformed("aggregation_group_type_index"));
            }
            return Err(ParseError::Unsupported("aggregation_group_type_index"));
        }
        let default_value = match required(document, "default_value")? {
            Value::Null => None,
            value if return_type.accepts(value) => Some(value.clone()),
            _ => return Err(ParseError::Malformed("default_value")),
        };
        let rules = required(document, "rules")?
            .as_array()
            .ok_or(ParseError::Malformed("rules"))?;
        if rules.len() > MAX_RULES {
            return Err(ParseError::LimitExceeded("rules"));
        }
        let mut seen = HashSet::with_capacity(rules.len());
        let rules = rules
            .iter()
            .map(|value| {
                let rule = Rule::parse(value, return_type)?;
                if !seen.insert(rule.id) {
                    return Err(ParseError::Malformed("rule.id"));
                }
                Ok(rule)
            })
            .collect::<Result<_, _>>()?;
        Ok(Self {
            default_value,
            rules,
            aggregation_group_type_index: None,
        })
    }

    #[doc(hidden)]
    pub fn estimated_heap_bytes(&self) -> usize {
        self.default_value
            .as_ref()
            .map_or(0, estimate_json_heap_size)
            + self.rules.capacity() * std::mem::size_of::<Rule>()
            + self
                .rules
                .iter()
                .map(Rule::estimated_heap_bytes)
                .sum::<usize>()
    }
}

impl Rule {
    fn parse(value: &Value, return_type: ReturnType) -> Result<Self, ParseError> {
        let rule = object(value, "rule")?;
        let rule_type = string(rule, "rule_type")?;
        let fields: &[&str] = match rule_type {
            "targeted_release" => TARGETED_RELEASE_FIELDS,
            "percentage_rollout" => PERCENTAGE_ROLLOUT_FIELDS,
            "experiment" => EXPERIMENT_FIELDS,
            _ => return Err(ParseError::Malformed("rule_type")),
        };
        closed(rule, fields, "rule")?;
        let id = string(rule, "id")?;
        // UUID's general parser also accepts compact and URN forms; the wire does not.
        if id.len() != 36 || [8, 13, 18, 23].iter().any(|&i| id.as_bytes()[i] != b'-') {
            return Err(ParseError::Malformed("rule.id"));
        }
        let id = Uuid::parse_str(id).map_err(|_| ParseError::Malformed("rule.id"))?;
        if rule.get("description").is_some_and(|v| !v.is_string()) {
            return Err(ParseError::Malformed("description"));
        }
        if rule.get("metadata").is_some_and(|v| !v.is_object()) {
            return Err(ParseError::Malformed("metadata"));
        }
        let targeting = properties::parse_targeting(required(rule, "targeting")?)?;
        let outcome = match rule_type {
            "targeted_release" => Outcome::TargetedRelease {
                value: typed_value(rule, return_type)?,
            },
            "percentage_rollout" => {
                let (rollout_percentage, on_rollout_miss, seed) = rollout(rule)?;
                Outcome::PercentageRollout {
                    value: typed_value(rule, return_type)?,
                    rollout_percentage,
                    on_rollout_miss,
                    seed,
                }
            }
            _ => {
                let paused = required(rule, "paused")?
                    .as_bool()
                    .ok_or(ParseError::Malformed("paused"))?;
                let (rollout_percentage, on_rollout_miss, seed) = rollout(rule)?;
                Outcome::Experiment {
                    paused,
                    rollout_percentage,
                    on_rollout_miss,
                    seed,
                    variants: variants(required(rule, "variants")?, return_type)?,
                    holdout: rule.get("holdout").map(holdout).transpose()?,
                }
            }
        };
        Ok(Self {
            id,
            targeting,
            outcome,
        })
    }

    fn estimated_heap_bytes(&self) -> usize {
        self.targeting.capacity() * std::mem::size_of::<Predicate>()
            + self
                .targeting
                .iter()
                .map(Predicate::estimated_heap_bytes)
                .sum::<usize>()
            + match &self.outcome {
                Outcome::PercentageRollout { seed, value, .. } => {
                    seed.capacity() + estimate_json_heap_size(value)
                }
                Outcome::TargetedRelease { value } => estimate_json_heap_size(value),
                Outcome::Experiment {
                    seed,
                    variants,
                    holdout,
                    ..
                } => {
                    seed.capacity()
                        + variants.capacity() * std::mem::size_of::<Variant>()
                        + variants
                            .iter()
                            .map(|v| v.key.capacity() + estimate_json_heap_size(&v.value))
                            .sum::<usize>()
                        + holdout.as_ref().map_or(0, |h| h.seed.capacity())
                }
            }
    }
}

fn typed_value(object: &Map<String, Value>, return_type: ReturnType) -> Result<Value, ParseError> {
    let value = required(object, "value")?;
    if !return_type.accepts(value) {
        return Err(ParseError::Malformed("value"));
    }
    Ok(value.clone())
}

fn rollout(rule: &Map<String, Value>) -> Result<(f64, RolloutMiss, String), ParseError> {
    if string(rule, "assignment_algorithm")? != "sha1_60_v1" {
        return Err(ParseError::Malformed("assignment_algorithm"));
    }
    if rule
        .get("assign_by")
        .is_some_and(|v| v.as_str() != Some("person"))
    {
        return Err(ParseError::Malformed("assign_by"));
    }
    let on_rollout_miss = match string(rule, "on_rollout_miss")? {
        "continue" => RolloutMiss::Continue,
        "return_default" => RolloutMiss::ReturnDefault,
        _ => return Err(ParseError::Malformed("on_rollout_miss")),
    };
    Ok((
        percentage(rule, "rollout_percentage")?,
        on_rollout_miss,
        seed(rule)?,
    ))
}

fn seed(object: &Map<String, Value>) -> Result<String, ParseError> {
    let seed = string(object, "seed")?;
    if !(1..=MAX_SEED_LENGTH).contains(&seed.chars().count()) {
        return Err(ParseError::Malformed("seed"));
    }
    Ok(seed.to_owned())
}

/// Weights are checked to two decimal places by the raw scan, so whole hundredths sum exactly.
fn variants(value: &Value, return_type: ReturnType) -> Result<Vec<Variant>, ParseError> {
    let items = value.as_array().ok_or(ParseError::Malformed("variants"))?;
    if items.len() > MAX_VARIANTS {
        return Err(ParseError::LimitExceeded("variants"));
    }
    if items.len() < MIN_VARIANTS {
        return Err(ParseError::Malformed("variants"));
    }
    let mut keys = HashSet::with_capacity(items.len());
    let mut hundredths = 0;
    let mut variants = Vec::with_capacity(items.len());
    for item in items {
        let variant = object(item, "variant")?;
        closed(variant, VARIANT_FIELDS, "variant")?;
        let key = string(variant, "key")?;
        if key.is_empty()
            || !key
                .bytes()
                .all(|b| b.is_ascii_alphanumeric() || b == b'_' || b == b'-')
            || !keys.insert(key)
        {
            return Err(ParseError::Malformed("variant.key"));
        }
        let weight = percentage(variant, "weight")?;
        hundredths += (weight * 100.0).round() as u32;
        variants.push(Variant {
            key: key.to_owned(),
            weight,
            value: typed_value(variant, return_type)?,
        });
    }
    if hundredths != 10_000 {
        return Err(ParseError::Malformed("variants"));
    }
    Ok(variants)
}

fn holdout(value: &Value) -> Result<Holdout, ParseError> {
    let holdout = object(value, "holdout")?;
    closed(holdout, HOLDOUT_FIELDS, "holdout")?;
    Ok(Holdout {
        seed: seed(holdout)?,
        exclusion_percentage: percentage(holdout, "exclusion_percentage")?,
    })
}

#[derive(Clone, Copy)]
enum ReturnType {
    Boolean,
    String,
    Number,
    Object,
}

impl ReturnType {
    /// Whether `value` is a non-null value of this type; a null default is handled by the caller.
    fn accepts(self, value: &Value) -> bool {
        match self {
            Self::Boolean => value.is_boolean(),
            Self::String => value.as_str().is_some_and(|s| !s.is_empty()),
            Self::Number => is_safe_number(value),
            Self::Object => value.is_object() && is_nested_value(value, 1),
        }
    }
}

fn is_safe_number(value: &Value) -> bool {
    value
        .as_f64()
        .is_some_and(|n| (-MAX_SAFE_INTEGER..=MAX_SAFE_INTEGER).contains(&n))
}

/// Depth counts object and array containers, with the returned object at level 1.
fn is_nested_value(value: &Value, depth: usize) -> bool {
    match value {
        Value::Object(map) => {
            depth <= MAX_OBJECT_DEPTH && map.values().all(|v| is_nested_value(v, depth + 1))
        }
        Value::Array(items) => {
            depth <= MAX_OBJECT_DEPTH && items.iter().all(|v| is_nested_value(v, depth + 1))
        }
        Value::Number(_) => is_safe_number(value),
        Value::Null | Value::Bool(_) | Value::String(_) => true,
    }
}

fn percentage(object: &Map<String, Value>, field: &'static str) -> Result<f64, ParseError> {
    let error = ParseError::Malformed(field);
    let Value::Number(number) = required(object, field)? else {
        return Err(error);
    };
    let numeric = number.as_f64().ok_or(error)?;
    if !numeric.is_finite() || !(0.0..=100.0).contains(&numeric) {
        return Err(error);
    }
    Ok(numeric)
}

fn object<'a>(value: &'a Value, field: &'static str) -> Result<&'a Map<String, Value>, ParseError> {
    value.as_object().ok_or(ParseError::Malformed(field))
}

fn required<'a>(
    object: &'a Map<String, Value>,
    field: &'static str,
) -> Result<&'a Value, ParseError> {
    object.get(field).ok_or(ParseError::Malformed(field))
}

fn string<'a>(object: &'a Map<String, Value>, field: &'static str) -> Result<&'a str, ParseError> {
    required(object, field)?
        .as_str()
        .ok_or(ParseError::Malformed(field))
}

fn closed(
    object: &Map<String, Value>,
    fields: &[&str],
    field: &'static str,
) -> Result<(), ParseError> {
    if object.keys().any(|key| !fields.contains(&key.as_str())) {
        return Err(ParseError::Malformed(field));
    }
    Ok(())
}